奇迹行者不吃牛肉——代码规范

[奇迹行者不吃牛肉]

这个作业属于哪个课程	202302软件工程实践
这个作业要求在哪里	团队作业—bate冲刺+事后诸葛亮
团队名称	奇迹行者不吃牛肉
这个作业的目标	制定代码规范
参考文献	华为云css代码规范、华为云JavaScript编码规范、华为之代码规范

@

代码规范目录

• 一、JS 代码
• 1.文件
• 2.命名
• 3.字符串
• 4.对象
• 5.数组
• 6.类型转换
• 二、CSS 代码
• 1.命名
• 2.class命名
• 3.选择器
• 4.属性书写顺序
• 5.语法
• 6.注释
• 三、代码排版规定
• 四、注释规范

一、JS 代码

1.文件

JavaScript 文件使用无 BOM 的 UTF-8 编码。

2.命名

1.构造函数采用大驼峰命名法

例如：function FistOne() {}

2.常量采用全大写的蛇形命名法

例如：const FIRST_ONE = 3

3.其他变量采用小驼峰命名法

4.一个函数作用域中所有的变量声明尽量提到函数首部，用一个var / let 声明，不允许出现两个连续的var声明。

例如：

function doSomethingWithItems(items) {
    // use one var
    var value = 10,
        result = value + 10,
        i,
        len;

    for (i = 0, len = items.length; i < len; i++) {
        result += 10;
    }

}

3.字符串

字符串开头和结束使用单引号 '

var str = '我是一个字符串';
var html = '<div class="cls">拼接HTML可以省去双引号转义</div>';

使用 数组 或 + 拼接字符串

// 使用数组拼接字符串
var str = [
    // 推荐换行开始并缩进开始第一个字符串, 对齐代码, 方便阅读.
    '<ul>',
        '<li>第一项</li>',
        '<li>第二项</li>',
    '</ul>'
].join('');

// 使用 `+` 拼接字符串
var str2 = '' // 建议第一个为空字符串, 第二个换行开始并缩进开始, 对齐代码, 方便阅读
    + '<ul>',
    +    '<li>第一项</li>',
    +    '<li>第二项</li>',
    + '</ul>';

使用字符串拼接的方式生成HTML，需要根据语境进行合理的转义。

// HTML 转义
var str = '<p>' + htmlEncode(content) + '</p>';

// HTML 转义
var str = '<input type="text" value="' + htmlEncode(value) + '">';

// URL 转义
var str = '<a href="/?key=' + htmlEncode(urlEncode(value)) + '">link</a>';

// JavaScript字符串 转义 + HTML 转义
var str = '<button onclick="check(\'' + htmlEncode(strLiteral(name)) + '\')">提交</button>';

4.对象

使用对象字面量 {} 创建新 Object。

// good
var obj = {};

// bad
var obj = new Object();

对象创建时，如果一个对象的所有 属性 均可以不添加引号，建议所有 属性 不添加引号。

var info = {
    name: 'someone',
    age: 28
};

对象创建时，如果任何一个 属性 需要添加引号，则所有 属性 建议添加 '。

// good
var info = {
    'name': 'someone',
    'age': 28,
    'more-info': '...'
};

// bad
var info = {
    name: 'someone',
    age: 28,
    'more-info': '...'
};

属性访问时，尽量使用 .。

属性名符合 Identifier 的要求，就可以通过 . 来访问，否则就只能通过 [expr] 方式访问。

info.age;
info['more-info'];

for in 遍历对象时, 使用 hasOwnProperty 过滤掉原型中的属性。

var newInfo = {};
for (var key in info) {
    if (info.hasOwnProperty(key)) {
        newInfo[key] = info[key];
    }
}

5.数组

使用数组字面量 [] 创建新数组，除非想要创建的是指定长度的数组。

// good
var arr = [];

// bad
var arr = new Array();

遍历数组不使用 for in。

数组对象可能存在数字以外的属性, 这种情况下 for in 不会得到正确结果。

var arr = ['a', 'b', 'c'];

// 这里仅作演示, 实际中应使用 Object 类型
arr.other = 'other things';

// 正确的遍历方式
for (var i = 0, len = arr.length; i < len; i++) {
    console.log(i);
}

// 错误的遍历方式
for (var i in arr) {
    console.log(i);
}

不因为性能的原因自己实现数组排序功能，尽量使用数组的 sort 方法。

清空数组使用 .length = 0。

6.类型转换

转换成 string 时，使用 + ''。

// good
num + '';

// bad
new String(num);
num.toString();
String(num);

转换成 number 时，通常使用 +

// good
+str;

// bad
Number(str);

string 转换成 number，要转换的字符串结尾包含非数字并期望忽略时，使用 parseInt。使用 parseInt 时，必须指定进制。

var width = '200px';
parseInt(width, 10);

// good
parseInt(str, 10);

// bad
parseInt(str);

转换成 boolean 时，使用 !!

var num = 3.14;
!!num;

number 去除小数点，使用 Math.floor / Math.round / Math.ceil，不使用 parseInt。

// good
var num = 3.14;
Math.ceil(num);

// bad
var num = 3.14;
parseInt(num, 10);

二、CSS 代码

1.命名

所有CSS选择符必须由英文字母、数字或“-”下划线组成，必须以字母开头，不能为纯数字。设计者要用有意义的单词或缩写组合来命名选择符，做到“见其名知其意”，这样就节省了查找样式的时间。样式名必须能够表示样式的大概含义（禁止出现如Div1、Div2、Style1等命名）。

当定义的样式名比较复杂时用下划线把层次分开，例如以下定义页面导航菜单选择符的CSS：

#nav_logo{…}
#nav_logo_ico{…}

2.class命名

• class 名称中只能出现小写字符和破折号（dashe）（不是下划线，也不是驼峰命名法）。破折号应当用于相关 class 的命名（类似于命名空间）（例如，.btn 和 .btn-danger）。
• 避免过度任意的简写。.btn 代表 button，但是 .s 不能表达任何意思。
• class 名称应当尽可能短，并且意义明确。
• 使用有意义的名称。使用有组织的或目的明确的名称，不要使用表现形式（presentational）的名称。
• 基于最近的父 class 或基本（base） class 作为新 class 的前缀。

/* Bad example */
.t { ... }
.red { ... }
.header { ... }
 
/* Good example */
.tweet { ... }
.important { ... }
.tweet-header { ... }

3.选择器

当一个 rule 包含多个 selector 时，每个选择器声明必须独占一行。

/* good */
 
.post,
 
.page,
 
.comment {
 
line-height:1.5;
 
}
 
/* bad */
 
.post,.page,.comment {
 
line-height:1.5;
 
}

4.属性书写顺序

同一 rule set 下的属性在书写时，应按功能进行分组，并以 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 等

5.语法

声明块的右花括号应当单独成行。

为了获得更准确的错误报告，每条声明都应该独占一行。

十六进制值应该全部小写，例如，#fff。

尽量使用简写形式的十六进制值，例如，用 #fff 代替 #ffffff。

避免为 0 值指定单位，例如，用 margin: 0; 代替 margin: 0px;。

6.注释

（1）结构性注释
结构性注释仅仅是用风格统一的大注释块从视觉上区分被分隔的部分，如以下代码所示：

/ *header(定义网页头部区域）------------------------- * /

（2）提示性注释
在编写CSS文档时，可能需要某种技巧解决某个问题。在这种情况下，最好将这个解决方案简要的注释在代码后面，如以下代码所示：

.news_list li span{
    float:left; / *设置新闻发布时间向左滑动，与新闻标题并列显示 * /
    width:80px;
    color:#999;/ * 定义新闻发布时间为灰色，弱化发布的时间在视觉上的感觉 */
}

三、代码排版规定

1.程序块要采用缩进风格编写，缩进空格数为4个。

2.相对独立程序块之间、变量阐明之后必要加空行。

3.较长语句（>80字符）要提成多行书写（在循环、判断等语句中的较长表达或者语句也是如此），长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出新行要进行恰当缩进，使排版整洁，语句可读。

4.若函数或者过程中参数过长，要进行恰当划分。

5.不允许把各种短语句写在一行中，即一行只写一条语句。

6.if, for, do, while, case, switch, default等语句自占一行，且无论语句多少都要加花括号{}。

7.对齐只使用空格键，不使用TAB键。

8.函数或过程开始、构造定义及循环、判断等语句中的代码都要采用缩进风格，case语句下状况解决语句也要遵从语句缩进规定。

9.程序块分界符（如大括号'{'和'}'）应各独占一行并且位于同一列，同步与引用它们语句左对齐。在函数体开始、类定义、构造定义、枚举定义以及if、for、do、while、case、switch、case语句中程序都应该采用上述缩进方式。如下是正确的：

if(条件)
{
    ...
}
else
{
    ...
}

四、注释规范

1.注释内容要清晰、明了，含义精确，防止注释二义性。

2.避免在注释中使用缩写。

3.注释应与其描述代码相近，对代码注释应放在其上方或右方（对单条语句注释）相邻位置，不可放在下面，如放于上方则需与其上面代码空行隔开。

4.对于所有有物理含义的变量、常量，如果其命名不是充分自注释，在声明时都必须加以注释，阐明其物理含义。变量、常量、宏注释应放在其上方相邻位置或右方。

5.注释应与所描述内容进行同样缩排。

6.将注释与其上面代码用空行隔开。

7.避免在一行代码或者表达式中间插入注释。

8.函数头部应进行注释，列出：函数目/功能、输入参数、输出参数、返回值、调用关系（函数、表）等。