前端开发规范
命名规范
- 避免使用缩写,除非缩写广泛接受并理解。
- 使用有意义的变量、函数和类名。
- 变量和函数名使用驼峰命名法(e.g.,
myVariableName
)。 - 常量全部大写。
- 类名使用帕斯卡命名法(e.g.,
MyClassName
)。 - 对于代码文件,文件名使用驼峰命名法(e.g., myFile.js or myFile.ts)。
- 对于静态文件,如图片文件,文件名使用蛇形命名法(e.g., my_file.png)。
- 目录使用使用驼峰命名法(e.g.,
myFolderName
)。 - 目录和非静态文件也可以用烤串命名法Kebab Case,但是烤串,就都烤串,保持一致性(my-folder-name)。
缩进和空格
- 使用两个空格进行缩进。
- 使用一致的缩进风格,不混用空格和制表符。
- 在代码块之间使用空行进行分隔,以提高可读性。
注释
- 使用注释来解释代码的关键部分和复杂逻辑。
- 使用注释文档化函数、方法和类的目的和参数。
- 删除不再需要的注释,以保持代码干净。
前端HTML规范
目的
本规范旨在确保前端开发项目中的HTML代码具有一致性,易于维护和理解。
基本规则
-
缩进和空格
- 使用两个空格作为缩进。
- 不要使用制表符。
- 在标签之间使用一个空格。
-
小写字母
- 所有HTML标签、属性和属性值应该使用小写字母。
-
文件编码
- 使用UTF-8编码作为HTML文档的字符编码。
-
注释
- 使用HTML注释来解释代码的功能,如
<!-- 这是一个注释 -->
。
- 使用HTML注释来解释代码的功能,如
-
自闭合标签
- 对于自闭合标签(如
<img>
、<input>
),不要在结束标签中添加斜杠,即使用<img>
而不是<img />
。
- 对于自闭合标签(如
结构
-
文档类型声明
- 使用HTML5文档类型声明:
<!DOCTYPE html>
。
- 使用HTML5文档类型声明:
-
文档结构
- 使用语义化标签如
<header>
、<nav>
、<main>
、<section>
等来组织文档内容。
- 使用语义化标签如
-
标题
- 每个页面应该有一个明确的
<title>
标签。
- 每个页面应该有一个明确的
-
语言属性
- 指定页面的语言属性:
<html lang="en">
。
- 指定页面的语言属性:
标签
-
嵌套规则
- 标签应该按照正确的嵌套规则嵌套,不要出现不正确的嵌套。
-
自定义属性
- 避免使用自定义属性,应该使用
data-*
属性来存储自定义数据。
- 避免使用自定义属性,应该使用
属性
-
引号
- 使用双引号来包裹属性值,如
<input type="text" class="input-text">
。
- 使用双引号来包裹属性值,如
-
布尔属性
- 对于布尔属性如
disabled
、checked
,不要添加属性值,直接使用属性名即可:<input type="checkbox" checked>
。
- 对于布尔属性如
CSS和JavaScript
-
外部资源
- 将CSS和JavaScript文件包含在HTML文档的底部,以避免阻塞页面加载。
-
内联样式和脚本
- 尽量避免使用内联样式和脚本,将样式和脚本从HTML中分离出来。
性能
-
图像优化
- 使用适当的图像格式(如WebP)和压缩工具以提高性能。
-
资源缓存
- 配置HTTP缓存头来提高资源的缓存性能。
验证和测试
-
HTML验证
- 使用HTML验证工具,如W3C验证器,来确保HTML代码的合法性。
-
跨浏览器测试
- 在不同浏览器和设备上测试页面,确保页面在各种环境下都能正确显示和工作。
参考链接
CSS规范 - Less 代码规范
本文档旨在定义Less样式表的编码规范,以确保代码的一致性和可维护性。遵循这些规则将有助于团队协作和项目的可持续性。
文件结构
1. 文件命名
- 使用有意义的文件名,描述文件中包含的样式内容。
- 使用小写字母和连字符(
-
)作为文件名的分隔符。
示例:
header.less
product-list.less
2. 文件组织
- 根据模块或功能将样式文件组织成目录。
- 避免创建过大的样式文件,应该根据需要拆分为多个文件。
示例:
styles/
├── common/
│ ├── typography.less
│ ├── layout.less
├── components/
│ ├── buttons.less
│ ├── forms.less
├── pages/
│ ├── home.less
│ ├── product.less
样式规范
3. 命名约定
- 使用有意义的类名和变量名,描述其用途而不是样式的外观。
- 使用小写字母和连字符作为类名和变量名的分隔符。
示例:
.header {
background-color: #333;
color: #fff;
}
$primary-color: #3498db;
4. 嵌套规则
- 使用嵌套规则以提高可读性,但不要滥用。
- 避免嵌套深度过深,通常不超过3层。
示例:
.nav {
ul {
li {
a {
color: #333;
&:hover {
color: #3498db;
}
}
}
}
}
5. 变量和Mixin
- 使用变量存储重复的值,如颜色、字体、尺寸等。
- 使用Mixin来组织可重复使用的样式规则。
示例:
@primary-color: #3498db;
.button {
color: #fff;
background-color: @primary-color;
border: 1px solid darken(@primary-color, 10%);
border-radius: 4px;
}
.rounded-corners() {
border-radius: 4px;
}
.element {
.rounded-corners();
background-color: #f5f5f5;
}
6. 注释
- 使用注释来解释样式的用途、兼容性注意事项、以及其他必要信息。
- 使用单行注释(
//
)来注释一行样式,使用块注释(/* */
)来注释多行或较大的代码块。
示例:
// 主标题样式
h1 {
font-size: 24px;
font-weight: bold;
}
/*
.sidebar 样式
注意:IE 11 不支持 flex 布局
*/
.sidebar {
display: flex;
// 其他样式规则
}
编码规范
7. 缩进和空格
- 使用两个空格作为缩进。
- 在属性和值之间使用一个空格。
- 在冒号后面加一个空格,如
property: value;
。
示例:
.header {
background-color: #333;
color: #fff;
margin: 10px 0;
}
8. 排版
- 使用一致的排版规则,如在大括号前换行,并在大括号后加空格。
- 使用单引号(
'
)而不是双引号("
)来定义字符串值。
示例:
.button {
color: #fff;
background-color: @primary-color;
}
9. 换行
- 样式规则之间使用空行分隔,提高可读性。
示例:
.header {
background-color: #333;
color: #fff;
}
.content {
font-size: 16px;
line-height: 1.5;
}
10. 良好的实践
- 避免使用
!important
,除非绝对必要。 - 避免使用通配符选择器(
*
)和ID选择器。 - 遵循DRY(不要重复自己)原则,避免重复的样式规则。
JavaScript规范
命名规范
-
变量和函数名
- 使用有意义的名称,避免单个字符的变量名。
- 使用驼峰命名法(camelCase)来命名变量和函数,例如:
myVariableName
。 - 类名使用帕斯卡命名法(PascalCase),例如:
MyClassName
。
-
常量
- 使用全大写字母和下划线(UPPER_CASE)来命名常量。
-
构造函数
- 构造函数的名称应以大写字母开头,例如:
function MyConstructor() {}
。
- 构造函数的名称应以大写字母开头,例如:
缩进和空格
-
缩进和空格
- 使用两个空格进行缩进。
- 不混用空格和制表符。
- 使用一致的缩进风格。
-
行尾空格
- 避免在行尾添加空格。
注释
-
代码注释
- 使用注释来解释代码的关键部分、复杂逻辑、以及不明显的业务规则。
- 使用多行注释(
/* ... */
)或单行注释(// ...
)根据情况选择。 - 注释应该清晰、简洁、和正确地反映代码的意图。
-
文档化注释
- 在函数、方法和类的定义上使用文档化注释,描述它们的目的、参数、返回值等信息。
变量和作用域
-
变量声明
- 始终使用
let
或const
来声明变量,避免使用var
。
- 始终使用
-
全局变量
- 最小化全局变量的使用,将变量限制在函数作用域或块作用域内。
-
变量的初始化
- 在声明变量时,始终进行初始化。
-
变量作用域
- 尽量将变量的作用域限制在最小范围内,避免全局作用域污染。
函数
-
函数声明
- 使用函数表达式或箭头函数而不是函数声明。
-
函数参数
- 使用有意义的参数名称。
- 避免过多的参数,最好控制在3-4个以内。
- 使用默认参数值,以避免未定义的参数值。
-
返回语句
- 每个函数应该有一个明确定义的返回语句。
- 避免在函数中早期返回。
-
函数长度
- 函数应保持短小,一般不超过20行。
条件语句和循环
-
条件语句
- 使用
if
,else if
,else
,switch
等条件语句来处理条件逻辑。 - 避免嵌套过深的条件语句。
- 使用
-
循环
- 使用
for
、while
和do...while
等循环结构来处理迭代。 - 避免无限循环。
- 使用
异步编程
- 异步编程
- 使用Promise、async/await等来处理异步操作,避免回调地狱。
模块化
- 模块化
- 使用ES6模块系统(
import
和export
)来组织代码。 - 避免全局变量和函数。
- 使用ES6模块系统(
错误处理
- 错误处理
- 使用
try...catch
块来处理可能的异常。 - 自定义错误类型,以便更好地识别错误的来源。
- 使用
示例
-
在块中始终使用括号以增加可读性:
// 好的... while (true) { shuffle() } // 不好的... while (true) shuffle() // 也不好... while (true) shuffle()
-
使用
===
比较运算符,以避免处理类型强制转换的复杂性。 -
一致使用引号,例如,只在代码中使用单引号或双引号,不要混合使用。除非有正当理由,否则更喜欢使用单引号,以便其中的 HTML 无需转义。例如:
// 好的... const foo = '只是一个普通的字符串' // 好的... const foo = '<a href="/bar">漂亮干净的 HTML 字符串</a>' // 不好的... const foo = "<a href=\"/bar\">带有转义双引号的 HTML 字符串</a>"
-
使用
event.preventDefault()
代替return false
以阻止默认事件操作。在考虑上下文为事件时,返回布尔值在语义上是不正确的。// 在这个上下文中,返回 false 没有意义 htmlElement.addEventListener('click', (e) => { // 做一些事情 return false }) // 使用 preventDefault htmlElement.addEventListener('click', (e) => { e.preventDefault() // 做一些事情 })
-
不再使用
var
- 我们有const
和let
,Babel 将根据需要进行编译。在 JavaScript 中,const
表示标识符不能被重新分配。let
表示变量可能会被重新分配,它还表示该变量只在其定义的块中使用。 -
单个 let 模式:
// 单个 let 模式: let mylet1 = 1, anotherlet2 = 'test', andAnotherlet = true // 这样可以吗? let mylet1 = 1, anotherlet2 = 'test' // 糟糕,自动分号插入在这里弹出了一个分号... andAnotherlet = true; // 现在是全局的 // 更好? let a = 1 , b = 2 , sum = a + b , myobject = {} , i , j // 传统的多个 let 模式: let myLet = 1 let anotherLet2 = 'test' let andAnotherLet = true
不要使用分号 - JavaScript 不需要它们
避免过多的函数参数
如果一个函数需要超过三个参数,考虑重构以使用配置对象:
// 不好
let myFunction1 = function(arg1, arg2, arg3, arg4) {}
myFunction1('firstArgument', argument2, true, 'My Third Argument')
// 好的
let myFunction2 = function(config) {}
myFunction2({
arg1: 'firstArgument',
arg2: argument2
arg3: true,
arg4: 'My Third Argument'
})
配置对象:
-
允许可选参数,
-
更易于阅读,
-
更易于维护。
命名约定
尽管我们可以推断 _oA
是一个私有对象,但我们对它将包含的值一无所知。
对于长寿命变量,请使用既有描述性又简洁的变量名称。避免在上下文之外使用可能被视为保留变量名称的名称。例如
,在 JavaScript 中,e
被视为事件对象。不要将其用于其他用途。
对于临时变量,即用于存储短寿命值的变量,例如用于迭代的变量,可以使用不具描述性的名称,例如 i, j, k
。
注释
注释您的代码。有两个原因您应该进行注释:
-
内联注释解释不能仅通过代码传达的设计或架构决策。这些主要是为了其他开发人员修改、扩展或调试代码的好处,但也适用于您 - 一周后您可能会回到代码并想知道它是如何工作的。
/** * 我是一个格式良好的注释 */ // 我是一个格式良好的简短单行注释 for (let i = 0; i < 10; i++); // 哎呀,不要在行尾添加注释 /* =================================================== * 哎呀,不要制定自己的注释格式 * ==================================================*/ // 这是一个长注释 // 它真的不应该 // 使用单行 // 注释语法。
-
为那些想要使用您的库/插件等而不阅读代码的用户提供 API 文档。使用 JSDoc 标准对文件和函数进行注释:
/** * @file 用于构建产品色板的 jQuery UI Widget * @author Joel Mitchell * @name $.cx.productSwatch * @dependencies: jQuery, jQuery UI widget 工厂(用于测试的 mockjax) */
/** * 用于关闭菜单的事件处理程序 * @param {Event} e jQuery 事件对象 */ var myFunction = function(e) {}
将代码分隔为单独的行
在适用的情况下,请确保代码写在单独的行上,以帮助 Git 差异和错误报告:
// 好的
page.setViewport({
width: 1280,
height: 1024
})
// 不太好
page.setViewport({width: 1280, height: 1024})
Vue规范
参考:https://v2.cn.vuejs.org/v2/style-guide/index.html
单文件组件的文件名应该要么始终是单词大写开头 (PascalCase),要么始终是横线连接 (kebab-case)。
对于绝大多数项目来说,在单文件组件和字符串模板中组件名应该总是 PascalCase 的——但是在 DOM 模板中总是 kebab-case 的。
PascalCase 相比 kebab-case 有一些优势:
编辑器可以在模板里自动补全组件名,因为 PascalCase 同样适用于 JavaScript。
如果你在模板中使用任何非 Vue 的自定义元素,比如一个 Web Component,PascalCase 确保了你的 Vue 组件在视觉上仍然是易识别的。
不幸的是,由于 HTML 是大小写不敏感的,在 DOM 模板中必须仍使用 kebab-case。
还请注意,如果你已经是 kebab-case 的重度用户,那么与 HTML 保持一致的命名约定且在多个项目中保持相同的大小写规则就可能比上述优势更为重要了。在这些情况下,在所有的地方都使用 kebab-case 同样是可以接受的
<!-- 在单文件组件和字符串模板中 -->
<MyComponent/>
<!-- 在 DOM 模板中 -->
<my-component></my-component>
<!-- 或者在所有地方 -->
<my-component></my-component>