个人总结的一个前端的规范文档.md
个人总结的一个前端的规范文档.md
WallenHan 发表于8个月前
个人总结的一个前端的规范文档.md
  • 发表于 8个月前
  • 阅读 28
  • 收藏 1
  • 点赞 0
  • 评论 0

腾讯云 技术升级10大核心产品年终让利>>>   

> 这个是平时在和前端打交道时发现一些小伙伴代码不够规范,遂有兴趣参考了国内外有公开规范的互联网公司的内容综合来总结出一个适合自己的.

> 中间有部分示例是一些经典问题的较优的解决方案,值得学习

正文如下


通用篇

多 IDE or 编辑器平台代码格式统一

Tab缩进 使用 4个Soft-Space 保证全平台代码表现一致性

> Eclipse设置在 Window->Preferences->general->editors->text editors display tab width:4 勾选 Insert Spaces for tabs Show Print Margin Print Margin column:80 其他编辑器 or IDE 类似设置。

不要混用tab和space;

不要在一处使用多个tab或space;

换行符统一用'LF'。

命名规则

项目命名

项目名全部采用小写方式, 以中划线分隔。 比如: my-project-name

目录名

目录名参照上一条规则,有复数结构时,要采用复数命名法,比如说: scripts, styles, images, data-models

HTML文件名

多个单词组成时,采用中划线连接方式,比如说: error-report.html

CSS,SCSS 样式文件命名

多个单词组成时,采用中划线连接方式,比如说:retina-sprites.scss


HTML 篇

HTML 基础配置

  • 文件应以<!DOCTYPE ......>首行顶格开始,推荐使用<!DOCTYPE html> 即HTML5文件头。
  • 必须申明文档的编码charset,且与文件本身编码保持一致,推荐使用UTF-8编码<meta charset="utf-8"/>
  • 根据页面内容和需求填写适当的keywordsdescription
  • 页面title是极为重要的不可缺少的一项。

** 示例代码 **

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <title>Welcome to SZUNICOM</title>
        <meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
        <meta name="keywords" content=""/>
        <meta name="description" content=""/>
        <meta name="viewport" content="width=device-width"/>
        <link rel="stylesheet" href="css/style.css"/>
        <link rel="shortcut icon" href="img/favicon.ico"/>
        <link rel="apple-touch-icon" href="img/touchicon.png"/>
    </head>
    <body>
    </body>
</html>

> keywords、 description 主要是针对网络爬虫有利于页面的SEO,提高权重,主要针对外部开放系统,内部系统可以忽略。

语义化使用 HTML 标签

HTML 标签属性应该按照特定的顺序出现以保证易读性

  • id
  • class
  • name
  • data-*
  • src, for, type, href
  • title, alt
  • aria-*, role

注释标准格式写法

代码说明的注释方法

> 解决无法定位所写注释对应的代码从哪里开始,又到哪里结束的问题。

  • 开始注释:&lt;!-- 注释说明 --&gt;(文案两头空格)。

  • 结束注释:&lt;!-- /注释说明 --&gt;(文案前加“/”符号,类似标签的闭合)。

  • 允许只有开始注释。

** 示例代码 **

<!-- 头部 -->
<div class="g-hd">
    <!-- LOGO -->
    <h1 class="m-logo"><a href="#">LOGO</a></h1>
    <!-- /LOGO -->
    <!-- 导航 -->
    <ul class="m-nav">
        <li><a href="#">NAV1</a></li>
        <li><a href="#">NAV2</a></li>
        <!-- 更多导航项 -->
    </ul>
    <!-- /导航 -->
</div>
<!-- /头部 -->

代码本身的注释方法

  • 单行代码的注释也保持同行,两端空格;
  • 多行代码的注释起始和结尾都另起一行并左缩进对齐。

** 示例代码 **

<!-- <h1 class="m-logo"><a href="#">LOGO</a></h1> -->
<!--
<ul class="m-nav">
    <li><a href="#">NAV1</a></li>
    <li><a href="#">NAV2</a></li>
</ul>
-->

CSS篇

CSS书写规范

  • 样式书写顺序

    只遵循横向顺序即可,先显示定位布局类属性,后盒模型等自身属性,最后是文本类及修饰类属性。

显示属性自身属性文本属性和其他修饰
displaywidthfont
visibilityheighttext-align
positionmargintext-decoration
floatpaddingvertical-align
clearborderwhite-space
list-styleoverflowcolor
topmin-widthbackground

> 在各种编辑器中使用css-comb插件可以实现自动排序 sublime、atom都支持

  • 最后一个值也以分号结尾

    通常在大括号结束前的值可以省略分号,但是这样做会对修改、添加和维护工作带来不必要的失误和麻烦。

  • 省略值为0时的单位

    为节省不必要的字节同时也使阅读方便,我们将0px、0em、0%等值缩写为0。

.m-box {
    margin:0 10px;
    background-position:50% 0;
}
  • 私有在前,标准在后

    先写带有浏览器私有标志的,后写W3C标准的。

.m-box {
    -webkit-box-shadow:0 0 0 #000;
    -moz-box-shadow:0 0 0 #000;
    box-shadow:0 0 0 #000;
}
  • 不要在颜色值 rgb() rgba() hsl() hsla()和 rect()中增加空格,并且不要带有取值前面不必要的 0 (比如,使用 .5 替代 0.5)。

CLASS 命名规则

使用单个字母加"-"为前缀

  • 布局(grid)(.g-);模块(module)(.m-);元件(unit)(.u-);功能(function)(.f-);皮肤(skin)(.s-);状态(.z-)。
功能说明英文名css缩写
布局将页面分割为几个大块,通常有头部、主体、主栏、侧栏、尾部等!grid.g-
模块一个语义化的可以重复使用的较大的整体!比如导航、登录、注册、各种列表、评论、搜索等module.m-
原件不可再分的较为小巧的个体,通常被重复用于各种模块中!比如按钮、输入框、loading、图标等unit.u-
功能一些常用样式的使用,我们将这些使用率较高的样式剥离出来,按需使用,通常这些选择器具有固定样式表现,比如清除浮动等!不可滥用!function.f-
皮肤你需要把皮肤型的样式抽离出来,通常为文字色、背景色(图)、边框色等,非换肤型网站通常只提取文字色!非换肤型网站不可滥用此类!skin.s-
状态状态类样式加入前缀,统一标识,方便识别,她只能组合使用或作为后代出现(.u-ipt.z-dis{},.m-list li.z-sel{})(因重名用拼音替代)status.z-
获取节点专用于JS获取节点,请勿使用.j-定义样式-.j-

> 注:在你样式中的选择器总是要以上面前五类开头,然后在里面使用后代选择器。如果这五类不能满足你的需求,你可以另外定义一个或多个大类,但必须符合单个字母+"-"为前缀的命名规则,即 .x- 的格式。

> 当前的工作环境中主要使用布局、模块、原件、功能、状态、节点选取前缀,皮肤作为后期有主题类界面开发预留。

示例代码

<style type="text/css">
    /* 图片居中溢出隐藏  */  
    .m-demo{
        position:relative;
        width:300px;
        height:300px;
        overflow:hidden;
        border:1px solid #ddd;
    }
    .m-demo p{
        position:absolute;
        top:50%;left:50%;
        margin:0;
        padding:0;
    }
    .m-demo img{
        position:absolute;
        top:-50%;
        left:-50%;
        display:block;
    }
    .m-demo img.hidden{
        visibility:hidden;
        position:static;
    }
</style>
<div class="m-demo">
    <p>
        <img src="http://nec.netease.com/img/s/1.jpg" class="hidden"/>
        <img src="http://nec.netease.com/img/s/1.jpg" alt=""/>
    </p>
</div>
<div class="m-demo">
    <p>
        <img src="http://nec.netease.com/img/m/1.jpg" class="hidden"/>
        <img src="http://nec.netease.com/img/m/1.jpg" alt=""/>
    </p>
</div>
<div class="m-demo">
    <p>
        <img src="http://nec.netease.com/img/l/1.jpg" class="hidden"/>
        <img src="http://nec.netease.com/img/l/1.jpg" alt=""/>
    </p>
</div>

一些常用模块class命名参考

模块class命名
header
内容content/container
footer
导航nav
侧栏sidebar
栏目column
页面外围控制整体佈局宽度wrapper
左右中left right center
登录条loginbar
标志logo
广告banner
页面主体main
热点hot
新闻news
下载download
子导航subnav
菜单menu
子菜单submenu
搜索search
友情链接friendlink
页脚footer
版权copyright
滚动scroll
内容content
标签tags
文章列表list
提示信息msg
小技巧tips
栏目标题title
加入joinus
指南guide
服务service
注册regsiter
状态status
投票vote
合作伙伴partner

备注标准格式写法

  • 对选择器的注释统一写在被注释对象的上一行,对属性及值的注释写于分号后。
  • 注释内容两端需空格,已确保即使在编码错误的情况下也可以正确解析样式。
  • 在必要的情况下,可以使用块状注释,块状注释保持统一的缩进对齐。

示例代码

/* 块状注释文字
 * 块状注释文字
 * 块状注释文字
 */
.m-list {
    width:500px;
}
.m-list li {
    height:20px;
    line-height:20px;/* 这里是对line-height的一个注释 */
    overflow:hidden;
}
.m-list li a {
    color:#333;
}
/* 单行注释文字 */
.m-list li em {
    color:#666;
}

让CSS做更多的事,减轻JS开发量。

  • 用CSS控制交互或视觉的变化,JS只需要更改className。
  • 利用CSS一次性更改多个节点样式,避免多次渲染,提高渲染效率。
  • 如果你的产品允许不兼容低版本浏览器,那么动画实现可以交给CSS。

JavaScript篇

部分代码书写约束

空行

  • 方法之间加
  • 单行或多行注释前加
  • 逻辑块之间加空行增加可读性
  • 变量命名
  • 文件最后保留一个空行

标准变量采用驼峰标识

  • 使用的ID的地方一定全大写
  • 使用的URL的地方一定全大写, 如 reportURL
  • 涉及Android的,一律大写第一个字母
  • 涉及iOS的,一律小写第一个,大写后两个字母
  • 常量采用大写字母,下划线连接的方式
  • 构造函数,大写第一个字母

示例代码

var thisIsMyName;   //注释说明
var goodID;     //注释说明
var AndroidVersion;     //注释说明
var iOSVersion;     //注释说明
var MAX_COUNT = 10;     //注释说明

/** 注释内容与星标前保留一个空格  */
function Person (name) {
    this.name = name;
}

使用帕斯卡式命名构造函数或类

示例代码

// bad
function user(options) {
    this.name = options.name;
}

var bad = new user({
    name: 'nope'
});

/** 骆驼命名法是首字母小写,而帕斯卡命名法是首字母大写。*/

**示例代码**
// good
function User(options) {
    this.name = options.name;
}

var good = new User({
    name: 'yup'
});

字符常量

  • 一般情况下统一使用 ' ' 单引号

数组、对象

  • 对象属性名不需要加引号;
  • 对象以缩进的形式书写,不要写在一行;
  • 数组、对象最后不要有逗号。

示例代码

// not good
var a = {
    'b': 1
};

var a = {b: 1};

var a = {
    b: 1,
    c: 2,
};

// good
var a = {
    b: 1,
    c: 2
};

事件命名

  • 添加节点事件的命名规则 on + 名词 + 动作 符合驼峰规则

    如页面上有一个editBtn的按钮,要给这个按钮添加点击事件时,可以命名成onEditBtnClick,如果是鼠标悬停,onEditBtnMouseover等这样的一种命名规则。

  • 除了事件的命名外,其他的所有回调函数都以cb开头。

    如item里对模块的回调,cache对外面的回调等都以cb开头 + 名词 + 动词。

不要使用下划线前/后缀

> JavaScript 并没有私有属性或私有方法的概念。虽然使用下划线是表示「私有」的一种共识,但实际上这些属性是完全公开的,它本身就是你公共接口的一部分。这种习惯或许会导致开发者错误的认为改动它不会造成破坏或者不需要去测试。长话短说:如果你想要某处为「私有」,它必须不能是显式提出的。

示例代码

// bad
this.__firstName__ = 'Panda';
this.firstName_ = 'Panda';
this._firstName = 'Panda';

// good
this.firstName = 'Panda';

括号

下列关键字后必须有大括号(即使代码块的内容只有一行):if, else, for, while, do, switch, try, catch, finally, with

示例代码

// not good
if (condition)
    doSomething();

// good
if (condition) {
    doSomething();
}

函数格式

  • 无论是函数声明还是函数表达式,'('前不要空格,但'{'前一定要有空格;

  • 函数调用括号前不需要空格;

  • 立即执行函数外必须包一层括号;

  • 不要给inline function命名;

  • 参数之间用空格逗号分隔,注意逗号后有一个空格。

示例代码

// no space before '(', but one space before'{'
var doSomething = function(item) {
    // do something
};

function doSomething(item) {
    // do something
}

// not good
doSomething (item);

// good
doSomething(item);

// requires parentheses around immediately invoked function expressions
(function() {
    return 1;
})();

// not good
[1, 2].forEach(function x() {
    ...
});

// good
[1, 2].forEach(function() {
    ...
});

// not good
var a = [1, 2, function a() {
    ...
}];

// good
var a = [1, 2, function() {
    ...
}];

// use ', ' between function parameters
var doSomething = function(a, b, c) {
    // do something
};

函数块中一些需要注意的问题

不要保存 this 的引用。使用 Function#bind

示例代码

// bad
function () {
  var self = this;
  return function () {
    console.log(self);
  };
}

// bad
function () {
  var that = this;
  return function () {
    console.log(that);
  };
}

// bad
function () {
  var _this = this;
  return function () {
    console.log(_this);
  };
}

// good
function () {
  return function () {
    console.log(this);
  }.bind(this);
}

> 这个做法比较激进,和国内的很多互联网公司的代码规范不太一样。

null的使用

适用场景:

  • 初始化一个将来可能被赋值为对象的变量
  • 与已经初始化的变量做比较
  • 作为一个参数为对象的函数的调用传参
  • 作为一个返回对象的函数的返回值

不适用场景:

  • 不要用null来判断函数调用时有无传参
  • 不要与未初始化的变量做比较

示例代码

// not good
function test(a, b) {
    if (b === null) {
        // not mean b is not supply
        ...
    }
}

var a;

if (a === null) {
    ...
}

// good
var a = null;

if (a === null) {
    ...
}

条件表达式例如 if 语句通过抽象方法 To Boolean 强制计算它们的表达式并且总是遵守如下规则:

  • 对象 被计算为 true
  • Undefined 被计算为 false
  • Null 被计算为 false
  • 布尔值 被计算为 布尔的值
  • 数字 如果是 +0、-0 或 NaN 被计算为 false,否则为 true
  • 字符串 如果是空字符串 '' 被计算为 false,否则为 true

示例代码

if ([0]) {
  // true
  // 一个数组就是一个对象,对象被计算为 true
}

// bad
if (name !== '') {
  // ...stuff...
}

// good
if (name) {
  // ...stuff...
}

// bad
if (collection.length > 0) {
  // ...stuff...
}

// good
if (collection.length) {
  // ...stuff...
}

减少 == != 的使用, 优先用严格比较条件 === !==;

其他细节问题

如果你的文件导出一个类,你的文件名应该与类名完全相同

示例代码

// file contents
class CheckBox {
  // ...
}
module.exports = CheckBox;

// in some other file
// bad
var CheckBox = require('./checkBox');

// bad
var CheckBox = require('./check_box');

// good
var CheckBox = require('./CheckBox');
标签: 编码规范 HTML
共有 人打赏支持
粉丝 4
博文 23
码字总数 19380
×
WallenHan
如果觉得我的文章对您有用,请随意打赏。您的支持将鼓励我继续创作!
* 金额(元)
¥1 ¥5 ¥10 ¥20 其他金额
打赏人
留言
* 支付类型
微信扫码支付
打赏金额:
已支付成功
打赏金额: