最佳原则
坚持制定好的代码规范。
无论团队人数多少,代码应该同出一门。
命名规则
项目命名
全部采用小写方式, 以下划线分隔。
例:my_project_name
目录命名
参照项目命名规则;
有复数结构时,要采用复数命名法。
例:scripts, styles, images, data_models
JS文件命名
全部采用小写方式, 以下划线分隔。
例:model.js, account_model.js
CSS文件命名
全部采用小写方式, 以下划线分隔。
例:style.css, common_style.css
HTML文件命名
全部采用小写方式, 以下划线分隔。
例:index.html, news_list.html
HTML
语法
- 缩进使用tab(4个空格);
- 嵌套的节点应该缩进;
- 在属性上,使用双引号,不要使用单引号;
- 属性名全小写,用中划线做分隔符;
- 对于无需自闭合的标签,不允许自闭合;
- 不要忽略可选的关闭标签,例:
</li>、</body>。
1 |
|
HTML5 doctype
在页面开头使用这个简单地doctype来启用标准模式,使其在每个浏览器中尽可能一致的展现;
虽然doctype不区分大小写,但是按照惯例,doctype大写。
1 |
|
lang属性
根据HTML5规范:
应在html标签上加上lang属性。这会给语音工具和翻译工具帮助,告诉它们应当怎么去发音和翻译。
1 |
|
字符编码
通过声明一个明确的字符编码,让浏览器轻松、快速的确定适合网页内容的渲染方式,通常指定为’UTF-8’。
1 |
|
IE兼容模式
用 <meta> 标签可以指定页面应该用什么版本的IE来渲染;
不同doctype在不同浏览器下会触发不同的渲染模式。
1 |
|
引入CSS, JavaScript
在 head 中引入页面需要的所有 CSS 资源
引入CSS 时必须指明 rel="stylesheet"
JavaScript 应当放在页面末尾,或采用异步加载
根据HTML5规范, 通常在引入CSS和JavaScript时不需要指明 type,因为 text/css 和 text/javascript 分别是他们的默认值。
1 | <!-- 外部 CSS --> |
Title标签声明
页面必须包含 title 标签声明标题
title 必须作为 head 的直接子元素,并紧随 charset 声明之后
title 中如果包含 ascii 之外的字符,浏览器需要知道字符编码类型才能进行解码,否则可能导致乱码。
1 |
|
favicon.ico
如有添加 favicon.ico,保证可以访问
1、在 Web Server 根目录放置 favicon.ico 文件。
2、使用 link 指定 favicon。
1 | <link rel="shortcut icon" href="path/to/favicon.ico"> |
viewport
若页面对移动设备友好,需指定页面的 viewport
设置 viewport 的 width 值来适应你的页面宽度。
同时因为不同移动设备分辨率不同,在设置时,应当使用 device-width 和 device-height 变量
为了使 viewport 正常工作,在页面内容样式布局设计上也要做相应调整,如避免绝对定位等。
viewport 的更多介绍,可以参见 Safari Web Content Guide的介绍
1 | <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1"> |
img 图片
禁止 img 的 src 取值为空
避免为 img 添加不必要的 title 属性
为重要图片添加 alt 属性
有下载需求的图片采用 img 标签实现,无下载需求的图片采用 CSS 背景图实现
添加 width 和 height 属性,以避免页面抖动
src 取值为空,会导致部分浏览器重新加载一次当前页面
多余的 title 影响看图体验,并且增加了页面尺寸
添加 alt 属性,可以提高图片加载失败时的用户体验。
产品 logo、生成的图片有潜在下载需求的图片,以 img 形式实现,能方便用户下载。
无下载需求的图片,比如:icon、背景、代码使用的图片等,尽可能采用 css 背景图实现。
JS生成标签
在JS文件中生成标签让内容变得更难查找,更难编辑,性能更差。应该尽量避免这种情况的出现。
减少标签数量
在编写HTML代码时,需要尽量避免多余的父节点;
很多时候,需要通过迭代和重构来使HTML变得更少。
1 | <!-- 不正确 --> |
实用高于完美
尽量遵循HTML标准和语义,但是不应该以浪费实用性作为代价;
任何时候都要用尽量小的复杂度和尽量少的标签来解决问题。
CSS
代码风格
缩进 使用tab(4个空格)。
不允许使用 2 个空格
1 | .element { |
分号
每个属性声明末尾都要加分号 ; 。
1 | .element { |
空格
以下几种情况不需要空格:
- 属性名后
- 多个规则的分隔符’
,‘前 !important‘!’后- 属性值中’(‘后和’)’前
- 行末不要有多余的空格
以下几种情况需要空格:
- 属性值前
- 选择器’>’, ‘+’, ‘~’前后
- ‘{‘前
!important‘!’前@else前后- 属性值中的’,’后
- 注释’/‘后和’/‘前
1 | /* 不正确写法 */ |
换行
以下几种情况不需要换行:
- ‘
{‘ 前
以下几种情况需要换行:
- ‘
{‘ 后和 ‘}‘ 前 - 每个属性独占一行
- 多个规则的分隔符’,’后
1 | /* 不正确写法 */ |
注释
注释统一用 ‘/* */‘,具体参照右边的写法;
缩进与下一行代码保持一致;
可位于一个代码行的末尾,与代码间隔一个空格。
1 | /* Modal header */ |
引号
最外层统一使用双引号;
url的内容要用引号;
属性选择器中的属性值需要引号。
1 | .element:after { |
命名
- 类名使用小写字母,以中划线分隔
- id采用驼峰式命名
- scss中的变量、函数、混合、placeholder采用驼峰式命名
1 | /* class */ |
属性声明顺序
同一规则下的属性在书写时,应按功能进行分组,并以 Formatting Model(布局方式、位置) > Box Model(尺寸) > Typographic(文本相关) > Visual(视觉效果) 的顺序书写,以提高代码的可读性。
解释:
- Formatting Model 相关属性包括:
position/top/right/bottom/left/float/display/overflow等 - Box Model 相关属性包括:
border/margin/padding/width/height等 - Typographic 相关属性包括:
font/line-height/text-align/word-wrap等 - Visual 相关属性包括:
background/color/transition/list-style等
另外,如果包含 content 属性,应放在最前面。
1 | .sidebar-nav { |
颜色
颜色16进制用小写字母;
颜色16进制尽量用简写。
1 | /* 不正确写法 */ |
属性简写
在可以使用缩写的情况下,尽量使用属性缩写。
1 | /* 不正确写法 */ |
样式选择器
选择器的嵌套层级应不大于 3 级,位置靠后的限定条件应尽可能精确
1 | /* 不正确写法 */ |
媒体查询
代码规则
1 | @media (min-width: 480px) { |
杂项
不允许有空的规则;
元素选择器用小写字母;
去掉小数点前面的0;
去掉数字中不必要的小数点和末尾的0;
属性值’0’后面不要加单位;
同个属性不同前缀的写法需要在垂直方向保持对齐,具体参照右边的写法;
无前缀的标准属性应该写在有前缀的属性后面;
不要在同个规则里出现重复的属性,如果重复的属性是连续的则没关系;
不要在一个文件里出现两个相同的规则;
用 border: 0; 代替 border: none;;
选择器不要超过4层(在scss中如果超过4层应该考虑用嵌套的方式来写);
发布的代码中不要有 @import;
尽量少用’*’选择器。
1 | /* 不正确写法 */ |
JavaScript
缩进
不允许使用 2 个空格,使用soft tab(4个空格)。
1 | var x = 1, |
单行长度
不要超过80,但如果编辑器开启word wrap可以不考虑单行长度。
分号
以下几种情况后需加分号:
- 变量声明
- 表达式
1 | /* 变量声明 */ |
空格
以下几种情况不需要空格:
- 对象的属性名后
- 前缀一元运算符后
- 后缀一元运算符前
- 函数调用括号前
- 无论是函数声明还是函数表达式,’(‘前不要空格
- 数组的’[‘后和’]‘前
- 对象的’{‘后和’}‘前
- 运算符’(‘后和’)‘前
以下几种情况需要空格:
- 二元运算符前后
- 三元运算符’?:‘前后
- 代码块’{‘前
- 下列关键字前:
else,while,catch,finally - 下列关键字后:
if,else,for,while,do,switch,case,try,catch,finally,with,return,typeof - 单行注释’//‘后(若单行注释和代码同行,则’//‘前也需要),多行注释’*****’后
- 对象的属性值前
for循环,分号后留有一个空格,前置条件如果有多个,逗号后留一个空格- 无论是函数声明还是函数表达式,’{‘前一定要有空格
- 函数的参数之间
1 | // 不正确写法 |
空行
以下几种情况需要空行:
- 变量声明后(当变量声明在代码块的最后一行时,则无需空行)
- 注释前(当注释在代码块的第一行时,则无需空行)
- 代码块后(在函数调用、数组、对象中则无需空行)
- 文件最后保留一个空行
1 | // 变量声明后需空白行 |
换行
换行的地方,行末必须有’,‘或者运算符;
以下几种情况不需要换行:
- 下列关键字后:
else,catch,finally - 代码块’{‘前
以下几种情况需要换行:
- 代码块’{‘后和’}’前
- 变量赋值后
1 | // 不正确写法 |
单行注释
双斜线后,必须跟一个空格;
缩进与下一行代码保持一致;
可位于一个代码行的末尾,与代码间隔一个空格。
1 | if (condition) { |
多行注释
最少三行, ‘*’后跟一个空格,具体参照右边的写法;
建议在以下情况下使用:
- 难于理解的代码段
- 可能存在错误的代码段
- 浏览器特殊的HACK代码
- 业务逻辑强相关的代码
1 | /* |
文档注释
各类标签@param, @method等请参考JSDoc Guide;
建议在以下情况下使用:
- 所有常量
- 所有函数
- 所有类
1 | /** |
引号
最外层统一使用单引号。
1 | // 不正确写法 |
变量命名
- 标准变量采用驼峰式命名(除了对象的属性外,主要是考虑到cgi返回的数据)
- ‘ID’在变量名中全大写
- ‘URL’在变量名中全大写
- ‘Android’在变量名中大写第一个字母
- ‘iOS’在变量名中小写第一个,大写后两个字母
- 常量全大写,用下划线连接
- 构造函数,大写第一个字母
- jquery对象必须以’$’开头命名
1 | var thisIsMyName; |
变量声明
一个函数作用域中所有的变量声明尽量提到函数首部,用一个var声明,不允许出现两个连续的var声明,用,号隔开就行了。
1 | function doSomethingWithItems(items) { |
函数
无论是函数声明还是函数表达式,’(‘前不要空格,但’{‘前一定要有空格;
函数调用括号前不需要空格;
立即执行函数外必须包一层括号;
参数之间用’, ‘分隔,注意逗号后有一个空格。
1 | // no space before '(', but one space before'{' |
数组、对象
对象属性名不需要加引号;
对象以缩进的形式书写,不要写在一行;
数组、对象最后不要有逗号。
1 | // 不正确写法 |
括号
下列关键字后必须有大括号(即使代码块的内容只有一行):if, else, for, while, do, switch, try。
1 | // 不正确写法 |
null
适用场景:
- 初始化一个将来可能被赋值为对象的变量
- 与已经初始化的变量做比较
- 作为一个参数为对象的函数的调用传参
- 作为一个返回对象的函数的返回值
不适用场景:
- 不要用null来判断函数调用时有无传参
- 不要与未初始化的变量做比较
1 | // 不正确写法 |
undefined
永远不要直接使用undefined进行变量判断;
使用typeof和字符串’undefined’对变量进行判断。
1 | // 不正确写法 |
编辑器配置
sublime3编辑器
- 安装sublime3组件 Package Control
- 按下 `ctrl+``
- 复制粘贴以下代码,粘贴以下代码到底部命令行并回车
import urllib.request,os,hashlib; h = 'eb2297e1a458f27d836c04bb0cbaf282' + 'd0e7a3098092775ccb37ca9d6b2e4b7d'; pf = 'Package Control.sublime-package'; ipp = sublime.installed_packages_path(); urllib.request.install_opener( urllib.request.build_opener( urllib.request.ProxyHandler()) ); by = urllib.request.urlopen( 'http://packagecontrol.io/' + pf.replace(' ', '%20')).read(); dh = hashlib.sha256(by).hexdigest(); print('Error validating download (got %s instead of %s), please try manual install' % (dh, h)) if dh != h else open(os.path.join( ipp, pf), 'wb' ).write(by) - 重启Sublime Text
- 如果在Perferences->package settings中看到package control这一项,则安装成功
- 安装sublime3插件
- 按下
ctrl+shift+p调出命令面板,输入’ip’(Install Package) - 输入以下插件的名字,按顺序逐个进行安装:
EmmetSublime AlignmentjQuerySublime CodeIntelBracket Highlighter
- 按下
Brackets编辑器
- 安装Brackets ,打开brackets.io 点击 Download Brackets
- 切换语言 1、Debug -> Switch Language 2、点开下拉菜单,选择你想要的语言 3、点击 Reload Brackets
- 安装Brackets插件
- 方法一:目录选择 文件 -> 扩展管理器
- 方法二:编辑器主界面右上角的闪电式的图标
- 打开扩展管理器以后,可以找到想要使用的扩展,点击安装(以下是常用扩展)
快速编辑代码 - Emmet改变样式 - Themes折叠代码块 - Code Folding自动格式化 - BeautifyJS 帮助文档 - QuickDocsJS
- 本文作者: LQbank
- 本文链接: http://example.com/2021/02/08/前端开发代码规范/
- 版权声明: 本博客所有文章除特别声明外,均采用 MIT 许可协议。转载请注明出处!