文档章节

个人总结的一个前端的规范文档.md

WallenHan
 WallenHan
发布于 2017/04/27 15:53
字数 3350
阅读 32
收藏 1
点赞 0
评论 0

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

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

正文如下


通用篇

多 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

注释标准格式写法

代码说明的注释方法

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

  • 开始注释:<!-- 注释说明 -->(文案两头空格)。

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

  • 允许只有开始注释。

** 示例代码 **

<!-- 头部 -->
<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');

© 著作权归作者所有

共有 人打赏支持
WallenHan
粉丝 3
博文 23
码字总数 19380
作品 0
西安
程序员
xiaozhuai/tiny_wiki

[English Readme] [中文文档] 关于 Tiny Wiki 是一个极简的在线文档中心, 它可以运行在现今流行的服务器环境上, 例如 apache+php 或 nginx+php Under the MIT License 作者 xiaozhuai xiaozh...

xiaozhuai
2016/12/12
0
0
如何打造一个令人愉悦的前端开发环境(一)

文章来源 最近几年,前端发展越来越迅速,各种萌新加入了前端这个大家庭,大有赶IOS、超Android的趋势呀!同时,萌新们提出了各种前端工作问题,除了最基础的html、css、js三板斧之外,最让人...

乖小鬼YQ
2017/11/29
0
0
mobile web 前端研发流程 【转载】

接触Mobile WEB前端开发将近一年时间了,在这不算短的时间里,通过吸取圆心、沉鱼等前辈们的经验以及不断的摸索和实战,总结出一套自己的Mobile WEB“研发流程”。为什么叫“研发”流程而不是...

石秋风
2012/04/18
0
2
基于koajs的web项目构建-心得篇

根据 基于koajs的web项目构建-入门篇 所描述的,建立了项目的基本目录结构,接下来的工作便是编码,编译,测试,发布。做为这些工作,每一项工作都有自己的学问,针对这三项工作的技巧分析文...

唯慕清风
2016/09/20
31
0
【开源访谈】bingoJS 作者 front-Y 访谈实录

【嘉宾介绍】 @front-Y ,纯粹的开发者,前端 MV* 开发框架 bingoJS 的作者,写的文档让红薯感动到哭。项目地址:http://git.oschina.net/bingoJS/bingoJS,文档 http://bingojs.mydoc.io/。...

孔小菜
2015/06/15
2.7K
16
史上最全的前端资源大汇总

1.前言 最近有很多朋友问我有没有相关的书籍推荐,希望能够自学一下前端。 正好最近在查阅文章的时候,发现有朋友已经进行过总结。 经过沟通和“行贿”��,终于取得转载权利,在此感谢晚晴...

mr_lp
2017/01/13
0
0
对你同样重要的非技术贴,一封有效的求职信的具体写法

接我的上篇博文《 对你同样重要的非技术贴,告诉你写求职信的9个技巧》。 一封有效的求职信字数应该控制在200字之内,要保持一个简单、清楚的格式布局。 求职信的格式可分为三段:求职、介绍...

半饱即好
2014/05/26
0
0
HTML5——对HTML5的认识

首先非常感谢李刚老师出的这本书《HTML5/CSS3/JavaScript讲义》,今天读了第一章节的内容,趁热打铁,总结一下。 HTML5的时代已经到来,它对所有的前端开发人员来说是一种福音。HTML5致力于解...

武小猪
06/26
0
0
前端架构设计指南(一): 代码核心

可能很多人和我一样, 首次听到"前端架构"这个词, 第一反应是: "前端还有架构这一说呢?" 在后端开发领域, 系统规划和可扩展性非常关键, 因此架构师备受重视, 早在开发工作启动之前, 他们就被邀...

Lee_tanghui
2017/11/24
0
0
php关于代码规范的一些小总结

以下信息是根据个人习惯进行整理,有什么不正确的地方,还请各位大牛指教 1.前端要进行基础的验证 一些很简单的基础验证要先在前端完成,例如输入框不允许为空,最基础的不为空的验证要在前端...

微雨初晴
2016/12/27
25
0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

CentOS “Destination Host Unreachable”问题解决办法

挑战极速安装CentOS时遇到局域网主机不能通信的情况: [root@zjd network-scripts]# ping 8.8.8.8PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.64 bytes from 8.8.8.8: icmp_seq=1 ttl=......

wffger
12分钟前
0
0
CentoOS6.6安装netcat

CentOS下安装netcat 使用zookeeper过程中,需要监控集群状态。在使用四字命令时(echo conf | nc localhost 2181),报出如下错误:-bash: netcat: command not found。 我的系统是CentOS 6....

ghou-靠墙哭
23分钟前
0
0
es6之解构赋值巧用

ES6 允许按照一定模式,从数组、对象等中提取值,对变量进行赋值,这被称为解构赋值。 如何进行解构赋值我这里就不赘述,本篇文章主要是将解构赋值的巧妙使用之处。 1、交互变量的值 常用交互...

秋季长青
28分钟前
0
0
Elasitcsearch High Level Rest Client学习笔记(三)批量api

Bulk Request BulkRequest可以在一起从请求执行批量添加、更新和删除,至少需要添加一个操作 BulkRequest request = new BulkRequest(); //创建BulkRequestrequest.add(new IndexRequest("...

木子SMZ
32分钟前
0
0
mybatis-dynamic sql

OGNL expressions if 判断是否存在值 <select id="findActiveBlogLike" resultType="Blog"> SELECT * FROM BLOG WHERE state = ‘ACTIVE’ <if test="title != null"> AND title like #{tit......

writeademo
39分钟前
0
0
社交系统ThinkSNS+ V1.8.3更新播报

     研发发布版本号:1.8.3   本次版本于2018年7月16日发布   本次发布类型:新增功能、细节调整与优化   社交系统ThinkSNSPlus更新体验:请于官网下载/安装最新版或联系QQ35159...

ThinkSNS账号
42分钟前
0
0
教育思考:选择编程是一场父母和孩子的和解[图]

教育思考:选择编程是一场父母和孩子的和解[图]: 之前有个很热的段子是这样讲的:深夜十点的时候,某小区一女子大声喊叫“什么关系?啊?!到底什么关系?你说!”最后发现原来是一位妈妈陪...

原创小博客
43分钟前
0
0
X64汇编之指令格式解析

最近由于项目组内要做特征码搜索的东西,便于去Hook一些未导出函数,你懂得...于是就闲着学习了一下x86/x64的汇编指令格式。x86的汇编指令格式请参照http://bbs.pediy.com/showthread.php?t...

simpower
46分钟前
0
0
rust 语法概要(只适合不熟悉时快速查阅使用,不适合理解其精髓。未完待续)

注意:本内容只适合快查,不适合理解精髓。精髓请研读 https://kaisery.github.io/trpl-zh-cn/foreword.html 基本数据类型 i8,i16,i32,i64,i128 u8,u16,u32,u64,u128 f32,f64 char bool:true...

捍卫机密
49分钟前
0
0
JS中严格模式和非严格模式

1,使用 严格模式的使用很简单,只有在代码首部加入字符串 "use strict"。必须在首部即首部指其前面没有任何有效js代码除注释,否则无效 2.注意事项 (1)不使用var声明变量严格模式中将不通...

AndyZhouX
49分钟前
0
0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部