码库记事本

码库记事本

Web前端开发规范2017(HTML/JavaScript/CSS)

小诸哥 0

前言
这是一份旨在增强团队的开发协作,提高代码质量和打造开发基石的编码风格规范,其中包含了 HTML, javascript 和 CSS/SCSS 这几个部分。我们知道,当一个团队开始指定并实行编码规范的话,错误就会变得更加显而易见。如果一段特定的代码不符合规范的话,它有可能只是代码风格错误,而也有可能会是 bug。早期指定规范就使得代码审核得以更好的开展,并且可以更精确的地定位到错误。只要开发者们能够保证源代码源文件都严格遵循规范,那接下去所使用的混淆、压缩和编译工具则可投其所好不尽相同。

要讲的依次为:

  • 前端编码规范(1)—— 一般规范
  • 前端编码规范(2)—— HTML规范
  • 前端编码规范(3)—— javaScript规范
  • 前端编码规范(4)—— CSS规范

一般规范

以下章节列举了一些可应用在 HTML, JavaScript 和 CSS/SCSS 上的通用规则。

文件/资源命名

  • 使用点分隔符(.)来区分文件名中带有清晰意义的元数据(如 .min.js, .min.css)
  • 使用减号(-)是用来分隔文件名(如 big-black-background.jpg)
  • 文件命名总是以字母开头而不是数字
  • 资源的字母名称必须全为小写

Web 项目中,所有的文件名应该都遵循同一命名约定。以可读性而言,减号(-)是用来分隔文件名的不二之选。同时它也是常见的 URL 分隔符(i.e. //example.com/blog/my-blog-entry or //s.example.com/images/big-black-background.jpg),所以理所当然的,减号应该也是用来分隔资源名称的好选择。
请确保文件命名总是以字母开头而不是数字。而以特殊字符开头命名的文件,一般都有特殊的含义与用处(比如 compass[1] 中的下划线就是用来标记跳过直接编译的文件用的)。
资源的字母名称必须全为小写,这是因为在某些对大小写字母敏感的操作系统中,当文件通过工具压缩混淆后,或者人为修改过后,大小写不同而导致引用文件不同的错误,很难被发现。
还有一些情况下,需要对文件增加前后缀或特定的扩展名(比如 .min.js, .min.css),抑或一串前缀(比如 3fa89b.main.min.css)。这种情况下,建议使用点分隔符来区分这些在文件名中带有清晰意义的元数据。

  1. 不推荐
  2.                  MyScript.js
  3.                  myCamelCaseName.css
  4.                  i_love_underscores.html
  5.                  1001-scripts.js
  6.                  my-file-min.css
  7.                 
  8.                 
  9. 推荐
  10.                  my-script.js
  11.                  my-camel-case-name.css
  12.                  i-love-underscores.html
  13.                  thousand-and-one-scripts.js
  14.                  my-file.min.css

协议


不要指定引入资源所带的具体协议。
当引入图片或其他媒体文件,还有样式和脚本时,URLs 所指向的具体路径,不要指定协议部分(http:, https:),除非这两者协议都不可用。
不指定协议使得 URL 从绝对的获取路径转变为相对的,在请求资源协议无法确定时非常好用,而且还能为文件大小节省几个字节。

  1. 不推荐
  2. <script src="http://cdn.com/foundation.min.js"></script>
  3. .example { background: url(http://static.example.com/images/bg.jpg);}
  4.  
  5. 推荐
  6. <script src="//cdn.com/foundation.min.js"></script>
  7. .example { background: url(//static.example.com/images/bg.jpg);}

文本缩进
一次缩进两个空格。

  1. HTML 代码
  2.      <ul>
  3. <li>Fantastic</li>
  4. <li>Great</li>
  5. <li>
  6. <a href="#">Test</a>
  7. </li>
  8. </ul>
  9.  
  10. CSS 代码
  11.      @media screen and (min-width: 1100px) {
  12. body {
  13. font-size: 100%;
  14. }
  15. }
  16. JavaScript 代码

注释

注释是你自己与你的小伙伴们了解代码写法和目的的唯一途径。特别是在写一些看似琐碎的无关紧要的代码时,由于记忆点不深刻,注释就变得尤为重要了。
编写自解释代码只是一个传说,没有任何代码是可以完全自解释的。而代码注释,则是永远也不嫌多。
当你写注释时一定要注意:不要写你的代码都干了些什么,而要写你的代码为什么要这么写,背后的考量是什么。当然也可以加入所思考问题或是解决方案的链接地址。

一些注释工具可以帮助你写出更好的注释。JSDoc 或 YUIDoc 就是用来写 JavaScript 注释用的。你甚至可以使用工具来为这些注释生成文档,这也是激励开发者们写注释的一个好方法,因为一旦有了这样方便的生成文档的工具,他们通常会开始花更多时间在注释细节上。

HTML规范

文档类型

推荐使用 HTML5 的文档类型申明:<!DOCTYPE html>.
(建议使用 text/html 格式的 HTML。避免使用 XHTML。XHTML 以及它的属性,比如 application/xhtml+xml 在浏览器中的应用支持与优化空间都十分有限)。

HTML 中最好不要将无内容元素的标签闭合,例如:使用 <br> 而非 <br />.

属性顺序

HTML 属性应当按照以下给出的顺序依次排列,确保代码的易读性:

class
id, name
data-*
src, for, type, href
title, alt
aria-*, role
class 用于标识高度可复用组件,因此应该排在首位。id 用于标识具体组件,应当谨慎使用(例如,页面内的书签),因此排在第二位。

  1.      <a class="..." id="..." data-modal="toggle" href="#">Example link </a>
  2. <input class="form-control" type="text">
  3. <img src="..." alt="...">

HTML 验证

一般情况下,建议使用能通过标准规范验证的 HTML 代码,除非在性能优化和控制文件大小上不得不做出让步。
使用诸如 W3C HTML validator 这样的工具来进行检测。
规范化的 HTML 是显现技术要求与局限的显著质量基线,它促进了 HTML 被更好地运用。

  1. 不推荐
  2.                  <title>Test</title>
  3.                  <article>This is only a test.
  4.         
  5.      推荐
  6.                  <!DOCTYPE html>
  7.                  <meta charset="utf-8">
  8.                  <title>Test</title>
  9.                  <article>This is only a test.</article>

语义化

根据元素(有时被错误地称作“标签”)其被创造出来时的初始意义来使用它。打个比方,用 heading 元素来定义头部标题,p 元素来定义文字段落,用 a 元素来定义链接锚点,等等。

HTML元素的排序规则,一般我们使用的HTML元素包括:div, p, ul, table, span, input, select。 基本上div, table, ul, p都属于结构性比较强的元素,而span, input则是比较弱的元素,因此不允许有span嵌套div, table等等的情况出现, span可以嵌套input, 可以嵌套span。程序员在写页面的时候可以先不考虑界面呈现,按照这样的规则,把数据直接绑定到HTML元素的节点上。

有根据有目的地使用 HTML 元素,对于可访问性、代码重用、代码效率来说意义重大。

HTML注释

1.每一独立部分都要表明注释。例如:

  1.      <!--右边 begin--> <!--右边end-->
  2. <!--左边 begin--><!--左边end-->
  3. <!--头部 begin--> <!--头部end-->
  4. <!--讲师列表 begin--> <!--讲师列表end-->

2.注释要用描述性语言,能够清楚的表达每一部分的意思

  1. <!--页面标头 begin-->
  2. <div id="top_frame">
  3. </div>
  4. <!--页面内容 begin-->
  5. <div id="main_frame">
  6. <!--菜单区域 begin-->
  7. <div id="menu_zone">
  8. <%=GetMenuHtml()%>
  9. </div>
  10. <!--菜单区域 end-->
  11. <!--折叠区域 begin-->
  12. <div id="switch">
  13. <span class="_switch"></span>
  14. </div>
  15. <!--折叠区域 end-->
  16. <!--内容区域 begin-->
  17. <div id="right_frame">
  18. <div id="main_zone">
  19. <asp:contentplaceholder id="ContentPlaceHolder1" runat="server">
  20. </asp:contentplaceholder>
  21. </div>
  22. </div>
  23. <!--内容区域 end-->
  24. </div>
  25. <!--页面内容 end-->

关注点分离

为了使文档成为可维护的干净整洁的代码,我们要尽可能的将信息(HTML 结构)、外观(CSS)和行为(JavaScript)分离开来,并使三者之间没有太多的交互和联系。

即在文档和模板中只包含结构性的 HTML;而将所有表现代码,移入样式表中;将所有动作行为,移入脚本之中。 为使得它们之间的联系尽可能的小,在文档和模板中也尽量少地引入样式和脚本文件。

清晰的分层意味着:

  • 不使用超过一到两张样式表(i.e. main.css, vendor.css)
  • 不使用超过一到两个脚本(学会用合并脚本)
  • 不使用行内样式(<style>.no-good {}</style>)
  • 不在元素上使用 style 属性(<hr style="border-top: 5px solid black">)
  • 不使用行内脚本(<script> alert('no good')</script>)
  • 不使用表象元素(i.e. , <u>, <center>, &lt;font>, )
  • 不使用表象 class 名(i.e. red, left, center)
  1. 不推荐
  2.                  <!DOCTYPE html>
  3.                  <html>
  4.                  <head>
  5.                  <link rel="stylesheet" href="base.css">
  6.                  <link rel="stylesheet" href="grid.css">
  7.                  <link rel="stylesheet" href="type.css">
  8.                  <link rel="stylesheet" href="modules/teaser.css">
  9.                  </head>
  10.                  <body>
  11.                  <h1 style="font-size: 3rem"></h1>
  12.                  I'm a subtitle and I'm bold!
  13.                  <center>Dare you center me!</center>
  14.                  <script>
  15.                  alert('Just dont...');
  16.                  </script>
  17.                  <div class="red">I'm important!</div>
  18.                  </body>
  19.                  </html>
  20.                 
  21.                 
  22.                 
  23.      推荐
  24.                  <!DOCTYPE html>
  25.                  <html>
  26.                  <head>
  27.                  <!-- Concatinate your style sheets into a single one -->
  28.                  <link rel="stylesheet" href="main.css">
  29.                  </head>
  30.                  <body>
  31.                  <!-- Don'use style attributes but assign sensible classes and apply styles in the stylesheet -->
  32.                  <h1 class="title"></h1>
  33.                  <!-- Don't use presentational elements and assign sensible classes -->
  34.                  <div class="sub-title">I'm a subtitle and I'm bold!</div>
  35.                  <!-- Maybe your comments get centered in your presentation but that decision is up to the stylesheet -->
  36.                  <span class="comment">Dare you center me!</span>
  37.                  <!-- You wanted to make it red because it's important so then also name the class important and decide in the stylesheet
  38.                  what you want to do with it -->
  39.                  <div class="important">I'm important!</div>
  40.                  <!-- Put all your scripts into files and concatinate them into a single one -->
  41.                  <script async src="main.js"></script>
  42.                  </body>
  43.                  </html>

HTML 内容至上

不要让非内容信息污染了你的 HTML。现在貌似有一种倾向:通过 HTML 来解决设计问题,这是显然是不对的。HTML 就应该只关注内容。
不要引入一些特定的 HTML 结构来解决一些视觉设计问题 不要将 img 元素当做专门用来做视觉设计的元素 以下例子展示了误将 HTML 用来解决设计问题的这两种情况:

  1. 不推荐
  2.                  <!-- We should not introduce an additional element just to solve a design problem -->
  3.                  <span class="text-box">
  4.                  <span class="square"></span>
  5.                  See the square next to me?
  6.                  </span>
  7.                 
  8.                  .text-box > .square {
  9.                  display: inline-block;
  10.                  width: 1rem;
  11.                  height: 1rem;
  12.                  background-color: red;
  13.                  }
  14.                 
  15.                 
  16.                 
  17. 推荐
  18.                  <!-- That's clean markup! -->
  19.                  <span class="text-box">
  20.                  See the square next to me?
  21.                  </span>
  22.                 
  23.                  /* We use a :before pseudo element to solve the design problem of placing a colored square in front of the text content */
  24.                  .text-box:before {
  25.                  content: "";
  26.                  display: inline-block;
  27.                  width: 1rem;
  28.                  height: 1rem;
  29.                  background-color: red;
  30.                  }

图片和 SVG 图形能被引入到 HTML 中的唯一理由是它们呈现出了与内容相关的一些信息。

  1. 不推荐
  2.                  <!-- Content images should never be used for design elements! -->
  3.                  <span class="text-box">
  4.                  <img src="square.svg" alt="Square" />
  5.                  See the square next to me?
  6.                  </span>
  7.                 
  8.                 
  9.                 
  10.                  推荐
  11.                  <!-- That's clean markup! -->
  12.                  <span class="text-box">
  13.                  See the square next to me?
  14.                  </span>
  15.                 
  16.                  /* We use a :before pseudo element with a background image to solve the problem */
  17.                  .text-box:before {
  18.                  content: "";
  19.                  display: inline-block;
  20.                  width: 1rem;
  21.                  height: 1rem;
  22.                  background: url(square.svg) no-repeat;
  23.                  background-size: 100%;
  24.                  }

HTML注意事项
Type 属性

省略样式表与脚本上的 type 属性。鉴于 HTML5 中以上两者默认的 type 值就是 text/css 和 text/javascript,所以 type 属性一般是可以忽略掉的。甚至在老旧版本的浏览器中这么做也是安全可靠的。

  1. 不推荐
  2.      <link rel="stylesheet" href="main.css" type="text/css">
  3.                  <script src="main.js" type="text/javascript"></script>
  4.                 
  5. 推荐
  6.      <link rel="stylesheet" href="main.css">
  7.                  <script src="main.js"></script>

HTML 引号

使用双引号(“”) 而不是单引号(”) 。

  1. 不推荐
  2.      <div class='news-article'></div>
  3.                 
  4. 推荐
  5.      <div class="news-article"></div>
  6.                 

属性值

属性一率小写,宽度、高度等要带上“px”

<img height="60px" width="760px" src="images/logo.gif"/>
给所有的属性赋值

  1. 不推荐
  2.      <input „„ checked />
  3.                 
  4. 推荐
  5. <input „„ checked= "checked"/>

网页中图片优化: 一定要加alt属性,alt属性指定了当图片不能显示的时候就显示供替换文本。 内容最好与关键词相关。

<img src="images/gxseo_logo.gif" alt="中英商务合作"/>
一些小图标最好用.gif格式图片,比如说箭头,文章列表前的图标等,在CSS中做成背景。 这些小图标最好做一张图片,用CSS来定位。

语言属性

根据 HTML5 规范: 强烈建议为 html 根元素指定 lang 属性,从而为文档设置正确的语言。这将有助于语音合成工具确定其所应该采用的发音,有助于翻译工具确定其翻译时所应遵守的规则等等。

  1.      <html lang="zh-CN">
  2. <!-- ... -->
  3. </html>

IE 兼容模式

IE 支持通过特定的 标签来确定绘制当前页面所应该采用的 IE 版本。除非有强烈的特殊需求,否则最好是设置为 edge mode,从而通知 IE 采用其所支持的最新的模式。

  1.      <meta http-equiv="X-UA-Compatible" content="IE=Edge">

字符编码

通过明确声明字符编码,能够确保浏览器快速并容易的判断页面内容的渲染方式。这样做的好处是,可以避免在 HTML 中使用字符实体标记(character entity),从而全部与文档编码一致(一般采用 UTF-8 编码)。

  1.      <head>
  2. <meta charset="UTF-8">
  3. </head>

前端编码规范(3)JavaScript 开发规范

JavaScript规范
变量声明
总是使用 var 来声明变量。如不指定 var,变量将被隐式地声明为全局变量,这将对变量难以控制。如果没有声明,变量处于什么定义域就变得不清(可以是在 Document 或 Window 中,也可以很容易地进入本地定义域)。所以,请总是使用 var 来声明变量。

采用严格模式带来的好处是,当你手误输入错误的变量名时,它可以通过报错信息来帮助你定位错误出处。

变量名

变量名推荐使用驼峰法来命名(camelCase)
全局变量为大写 (UPPERCASE )
常量 (如 PI) 为大写 (UPPERCASE )
函数: 构造函数始终以大写字母开头,非构造函数以一个小写字母开头
变量名不要以 $ 作为开始标记,避免与很多 JavaScript 库冲突

标签: Web 前端 开发 CSS