### 软件编程规范
在当前软件行业迅猛的发展下,软件逐渐走向大型化。在这种软件走向大型化的形势下,一个软件需要众多的人参与。比如一个操作系统的开发需要上千人的工作。这样我们就不得不面临着如何管理。
只要是一个有用的软件就需要大量的工作,首先要进行[软件需求分析](https://baike.baidu.com/item/%E8%BD%AF%E4%BB%B6%E9%9C%80%E6%B1%82%E5%88%86%E6%9E%90/10986816),然后要设计出软件的框架,而实现软件的代码仅占很少一部分(约20%)。而你不要小看这代码的实现,也是要很多人的参与的,一般[软件代码](https://baike.baidu.com/item/%E8%BD%AF%E4%BB%B6%E4%BB%A3%E7%A0%81/3030633)就有上千行,更别说操作系统了,据说Linux就有千万行的代码。这就需要把一个软件分成很多小的模块,分工完成。
搭建项目结构的起步过程,合适的命名规范、模块的划分、目录(包)的命名,如果做的足够好,别人导入项目后可能只需要10分钟就可以大概了解系统结构。
### 开发规范的目的
* 养成良好的编程习惯;
* 写出清楚、易懂、易维护的程序代码;
* 提高协同、开发效率;
* 减少编码过程中不必要的错误;
* 降低企业成本。
**制定一个符合自己公司情况的开发规范是很简单的,重要的是我们能够认识到规范的重要性,并坚持规范的开发习惯。**
#### HTML
省略图片、样式、脚本以及其他媒体文件 URL 的协议部分([http:,https:](http://%2Chttps/)),除非文件在两种协议下都不可用。这种方案称为 protocol-relative URL,好处是无论你是使用 HTTPS 还是 HTTP 访问页面,浏览器都会以相同的协议请求页面中的资源,同时可以节省一部分字节。
**协议**
~~~
<!-- Not recommended -->
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
<!-- Recommended -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
/* Not recommended */
.example {
background: url("https://www.google.com/images/example");
}
/* Recommended */
.example {
background: url("//www.google.com/images/example");
}
~~~
**缩进**
一次缩进2个空格,不要使用 tab 或者混合 tab 和空格的缩进。
~~~
<ul>
<li>Fantastic
<li>Great
</ul>
.example {
color: blue;
}
~~~
**大小写**
推荐使用小写字母,小写风格看起来更加清爽,容易识别和编写。
~~~
<!-- Not recommended -->
<A HREF="/">Home</A>
/* Not recommended */
color: #E5E5E5;
<!-- Recommended -->
<img src="google.png" />
/* Recommended */
color: #e5e5e5;
~~~
**代码注释**
采用类似标签闭合的写法,与HTML统一格式;注释文案两头空格,与CSS注释统一格式。
* 开始注释:(注释两头空格)。
* 结束注释:(注释前加`/`符号,类似标签的闭合)。
* 允许只有开始注释
~~~html
<body>
<!-- 侧栏内容区 -->
<div class="m-side">
<div class="side">
<div class="sidein">
<!-- 热门标签 -->
<div class="sideblk">
<div class="m-hd3"><h3 class="tit">热门标签</h3> </div>
...
</div>
<!-- 最热TOP5 -->
<div class="sideblk">
<div class="m-hd3">
<h3 class="tit">最热TOP5</h3>
<a href="#" class="s-fc02 f-fr">更多»</a>
</div>
...
</div>
</div>
</div>
</div>
<!-- /侧栏内容区 -->
</body>
~~~
**HTML 正确性**
尽可能使用正确的 HTML。
~~~
<!-- Not recommended -->
<title>Test</title>
<article>This is only a test.
<!-- Recommended -->
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>
~~~
**HTML 语义化**
根据使用场景选择正确的 HTML 元素(有时被错误的称为“标签”)。例如,使用 h1 元素创建标题,p 元素创建段落,a 元素创建链接等等。正确的使用 HTML 元素对于可访问性、可重用性以及编码效率都很重要。
~~~
<!-- Not recommended -->
<div onclick="goToRecommendations();">All recommendations</div>
<!-- Recommended -->
<a href="recommendations/">All recommendations</a>
~~~
**多媒体元素降级**
对于像图片、视频、canvas 动画等多媒体元素,确保提供其他可访问的内容。图片可以使用替代文本(alt),视频和音频可以使用文字版本。
~~~
<!-- Not recommended -->
<img src="spreadsheet.png">
<!-- Recommended -->
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
~~~
**合理的结构布局**
* 按照从上至下、从左到右的视觉顺序书写HTML结构。
* 用`<div>`代替`<table>`布局,但表现具有明显表格形式的数据,首选`<table>`。
* 结构上如果可以并列书写,就不要嵌套。
* 如果可以写成`<div></div><div></div>`那么就不要写成`<div><div></div></div>`
* 如果结构已经可以满足视觉和语义的要求,那么就不要有额外的冗余的结构。
* 如果`<div><h2></h2></div>`已经满足要求,那么就不要再写成`<div><div><h2></h2></div></div>`
**页面结构命名参考**
1. page: 代表整个页面,用于最外层。
2. wrap: 外套,将所有元素包在一起的一个外围包,用于最外层
3. wrapper: 页面外围控制整体布局宽度,用于最外层
4. container: 一个整体容器,用于最外层
5. head, header: 页头区域,用于头部
6. nav: 导航条
7. content: 内容,网站中最重要的内容区域,用于网页中部主体
8. main: 网站中的主要区域(表示最重要的一块位置),用于中部主体内容
9. column: 栏目
10. sidebar: 侧栏
11. foot, footer: 页尾、页脚。网站一些附加信息放置区域,(或命名为 copyright)用于底部
#### CSS
**语义化命名**
id和class的命名时要有效反应元素目的和用途的名称,或其他通用的名称,不要使用表象和晦涩难懂的名称。应该根据`他们是什么`来为元素命名,而不应该根据`他们的外观如何`来命名。
~~~xml
/* Not recommended */
<div class="red">
<div class="top_nav">
/* Not recommended */
<div class="button_green"></div>
<div class="clear "></div>
/* Recommended */
<div class="error"></div>
<div class="login"></div>
<div class="main_nav">
~~~
id 和 class 应该尽量简短,同时要容易理解。
~~~
/* Not recommended */
#navigation {}
.atr {}
/* Recommended */
#nav {}
.author {}
~~~
**CSS书写顺序**
1. 位置属性(position, top, right, z-index, display, float等)
2. 大小(width, height, padding, margin)
3. 文字系列(font, line-height, letter-spacing, color- text-align等)
4. 背景(background, border等)
5. 其他(animation, transition等)
~~~css
<!--推荐写法-->
.heavy{
position: absolute;
top: 0;
left: 10px;
width: 100px;
color: #008000;
background: url(../img/logo.pg) no-repeat left center;
}
~~~
**选择器**
除非需要,否则不要在 id 或 class 前加元素名。
~~~
/* Not recommended */
ul#example {}
div.error {}
/* Recommended */
#example {}
.error {}
~~~
**属性简写**
尽量使用 CSS 中可以简写的属性 (如 font),可以提高编码效率以及代码可读性。
~~~
/* Not recommended */
border-top-style: none;
font-family: palatino, georgia, serif;
font-size: 100%;
line-height: 1.6;
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;
/* Recommended */
border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;
~~~
**0 和单位**
值为 0 时不用添加单位,值在 -1 和 1 之间时,不需要加 0。
~~~
margin: 0;
padding: 0;
font-size: .8em;
~~~
**推荐使用子选择器,避免使用标签名**
~~~xml
<!--推荐写法-->
.warp> .heavy{
font-size: 14px;
}
<!--不推荐写法-->
.warp span{
font-size: 14px;
}
~~~
**命名空间**
给最外层的父容器设置选择器防止命名冲突,同时提高代码可维护性。
~~~
.adw_container {}
#note_container {}
~~~
**选择器命名分隔符**
选择器中使用连字符可以提高可读性。
~~~
/* Not recommended: does not separate the words “demo” and “image” */
.demoimage {}
/* Not recommended: uses underscore instead of hyphen */
.error_status {}
/* Recommended */
#video-id {}
.ads-sample {}
~~~
**内容缩进**
为了反映层级关系和提高可读性,块级内容都应缩进。
~~~
@media screen, projection {
html {
background: #fff;
color: #444;
}
}
~~~
**声明结束**
每行 CSS 都应以分号结尾。
~~~
/* Not recommended */
.test {
display: block;
height: 100px
}
/* Recommended */
.test {
display: block;
height: 100px;
}
~~~
**属性名结尾**
属性名和值之间都应有一个空格。
~~~
/* Not recommended */
h3 {
font-weight:bold;
}
/* Recommended */
h3 {
font-weight: bold;
}
~~~
**声明样式块的分隔**
在选择器和 {} 之间用空格隔开。
~~~
/* Not recommended: missing space */
#video{
margin-top: 1em;
}
/* Not recommended: unnecessary line break */
#video
{
margin-top: 1em;
}
* Recommended */
#video {
margin-top: 1em;
}
~~~
**选择器分隔**
每个选择器都另起一行。
~~~
/* Not recommended */
a:focus, a:active {
position: relative; top: 1px;
}
/* Recommended */
h1,
h2,
h3 {
font-weight: normal;
line-height: 1.2;
}
~~~
**规则分隔**
规则之间都用空行隔开。
~~~
html {
background: #fff;
}
body {
margin: auto;
width: 50%;
}
~~~
**CSS 引号**
属性选择器和属性值用单引号,URI 的值不需要引号。
~~~
/* Not recommended */
@import url("//www.google.com/css/maia.css");
html {
font-family: "open sans", arial, sans-serif;
}
/* Recommended */
@import url(//www.google.com/css/maia.css);
html {
font-family: 'open sans', arial, sans-serif;
}
~~~
**分段注释**
用注释把 CSS 分成各个部分。
~~~
/* Header */
#adw_header {}
/* Footer */
#adw_footer {}
/* Gallery */
.adw_gallery {}
~~~
**文本命名参考**
1. index.css: 一般用于首页建立样式
2. head.css: 头部样式,当多个页面头部设计风格相同时使用。
3. base.css: 共用样式。
4. style.css: 独立页面所使用的样式文件。
5. global.css: 页面样式基础,全局公用样式,页面中必须包含。
6. layout.css: 布局、版面样式,公用类型较多时使用,一般用在首页级页面和产品类页面中
7. module.css: 模块,用于产品类页,也可与其它样式配合使用。
8. master.css: 主要的样式表
9. columns.css: 专栏样式
10. themes.css: 主体样式
11. forms.css: 表单样式
12. mend.css: 补丁,基于以上样式进行的私有化修补。
**导航命名参考**
1. nav, navbar, navigation, nav_wrapper: 导航条或导航包,代表横向导航
2. top_nav: 顶部导航
3. main_nav: 主导航
4. sub_nav: 子导航
5. sidebar: 边导航
6. left_sidebar: 左导航
7. right_sidebar: 右导航
8. title: 标题
9. summary: 摘要
10. menu: 菜单,区域包含一般的链接和菜单
11. sub_menu: 子菜单
12. drop: 下拉
13. dorp_menu: 下拉菜单
14. links: 链接菜单
**功能命名**
1. logo: 标记网站logo标志
2. banner: 标语、广告条、顶部广告条
3. login: 登陆,(例如登录表单:form_login)
4. login_bar: 登录条
5. register: 注册
6. tool, toolbar: 工具条
7. search: 搜索
8. search_bar: 搜索条
9. search_input: 搜索输入框
10. shop: 功能区,表示现在的
11. icon: 小图标
12. label: 商标
13. homepage: 首页
14. subpage: 二级页面子页面
15. hot: 热门热点
16. list: 文章列表,(例如:新闻列表:list_news)
17. scroll: 滚动
18. tab: 标签
19. sitemap: 网站地图
20. message: 提示信息
21. current: 当前的
22. joinus: 加入
23. status: 状态
24. btn: 按钮,(例如:搜索按钮可写成:btn_search)
25. tips: 小技巧
26. note: 注释
27. guild: 指南
28. arr, arrow: 标记箭头
29. service: 服务
30. breadcrumb: (即页面所处位置导航提示)
31. download: 下载
32. vote: 投票
33. site_info: 网站信息
34. partner: 合作伙伴
35. link, friend_link: 友情链接
36. copyright: 版权信息
37. siteinfo_credits: 信誉
38. siteinfo_legal: 法律信息
### Javascript
**命名规范**
**驼峰式命名法介绍**
* 大驼峰式命名法 ```StudentInfo、UserInfo、ProductInfo```
* 小驼峰式命名法 ```studentInfo、userInfo、productInfo```
**变量**
* 命名方法:小驼峰式命名法
* 命名规范:前缀应当是动词。(函数的名字前缀为动词,以此区分变量和函数)。
* 命名建议:尽量在变量名字中体现所属类型,如:length、count等表示数字类型;而包含name、title表示为字符串类型。
~~~csharp
// 推荐
const maxCount = 10;
const tableTitle = 'LoginTable';
// 不推荐
const setCount = 10;
const getTitle = 'LoginTable';
~~~
**函数**
* 命名方法:小驼峰式命名法
* 命名规范:前缀应当是名词。(函数的名字前缀为动词,以此区分变量和函数)
* 动词建议:参考下表
| 动词 | 含义 | 动词 | 含义 |
| :---: | :---: | :---: | :---: |
| can | 能够 | transfer | 转换 |
| has | 含有 | finish | 完成 |
| is | 判断是否为某值 | append | 添加 |
| get | 获取某值 | set | 设置某值 |
| load | 加载数据 | save | 保存 |
| add | 添加 | remove | 删除 |
| create | 创建 | destory | 销毁 |
| start | 启动 | stop | 停止 |
| open | 打开 | close | 关闭 |
| read | 读取 | write | 写入 |
| begin | 开始 | end | 结束 |
| backup | 备份 | restore | 恢复 |
| import | 导入 | export | 导出 |
| split | 分割 | merge | 合并 |
| inject | 注入 | extract | 提取 |
| attach | 附着 | detach | 脱离 |
| bind | 绑定 | separate | 分离 |
| view | 查看 | browse | 浏览 |
| edit | 编辑 | modify | 修改 |
| select | 选取 | mark | 标记 |
| copy | 拷贝 | paste | 粘贴 |
| undo | 撤销 | redo | 重做 |
| insert | 插入 | delete | 移除 |
| clean | 清理 | clear | 清除 |
| index | 索引 | sort | 排序 |
| find | 查找 | search | 搜索 |
| increase | 增加 | decrease | 减少 |
| play | 播放 | pause | 暂停 |
| launch | 启动 | run | 运行 |
| compile | 编译 | execute | 执行 |
| debug | 调试 | trace | 跟踪 |
| observe | 观察 | listen | 监听 |
| build | 构建 | publish | 发布 |
| input | 输入 | output | 输出 |
| encode | 编码 | decode | 解码 |
| compress | 压缩 | decompress | 解压缩 |
| pack | 打包 | unpack | 解包 |
| parse | 解析 | emit | 生成 |
| connect | 连接 | disconnect | 断开连接 |
| send | 发送 | recive | 接收 |
| download | 下载 | upload | 上传 |
| refresh | 刷新 | synchronize | 同步 |
| lock | 锁定 | unlock | 解锁 |
| check out | 迁出 | check in | 迁入 |
| update | 更新 | revert | 复原 |
| submit | 提交 | commit | 交付 |
| push | 推 | pull | 拉 |
| expand | 展开 | collapse | 折叠 |
| begin | 开始 | end | 结束 |
| enter | 进入 | exit | 退出 |
| abort | 放弃 | quit | 离开 |
| collect | 收集 | aggregate | 聚集 |
| obsolete | 废弃 | depreciate | 废旧 |
~~~jsx
// 是否可阅读
function canRead() {
return true;
}
// 获取名称
function getName() {
return this.name;
}
~~~
**常量**
* 命名方法:名称全部大写。
* 命名规范:使用大写字母和下划线来组合命名,下划线用以分割单词。
~~~csharp
const MAX_COUNT = 10;
const URL = 'http://www.xxx.com';
~~~
**构造函数**
* 命名方法:大驼峰式命名法,首字母大写。
~~~jsx
function Student(name) {
this.name = name;
}
var st = new Student('tom');
~~~
**类的成员**
* 公共属性和方法:跟变量和函数的命名一样
* 私有属性和方法:前缀为\_(下划线),后面跟公共属性和方法一样的命名方式
~~~jsx
function Student(name) {
// 私有成员
var _name = name;
// 公共方法
this.getName = function () {
return _name;
}
// 公共方式
this.setName = function (value) {
_name = value;
}
}
var st = new Student('tom');
st.setName('jerry');
// => jerry:输出_name私有变量的值
console.log(st.getName());
~~~
**单行注释**
* 说明:单行注释以两个斜线开始,以行尾结束
* 语法:// 这是单行注释
* 使用方式://(双斜线)与注释文字之间保留一个空格。
~~~csharp
// 调用了一个函数
setTitle();
~~~
**多行注释**
* 说明:以/*开头,*/结尾
* 语法:/\* 注释说明 \*/
* 使用方式:至少三行注释时,第一行为/*,最后行为*/,其他行以*开始,并且注释文字与*保留一个空格。
~~~cpp
/*
* 代码执行到这里后会调用setTitle()函数
* setTitle():设置title的值
*/
setTitle();
~~~
**函数(方法)注释**
* 说明:函数(方法)注释也是多行注释的一种,但是包含了特殊的注释要求
* 语法:如下
~~~dart
/**
* 函数说明
* @关键字
*/
~~~
| 注释名 | 语法 | 含义 | 示例 |
| :---: | :---: | :---: | :---: |
| @param | @param 参数名 {参数类型} 描述信息 | 描述参数的信息 | @param name {String} 传入名称 |
| @return | @return {返回类型} 描述信息 | 描述返回值的信息 | @return {Boolean} true:可执行;false:不可执行 |
| @autho | @author 作者信息 \[附属信息:如邮箱、日期\] | 描述此函数作者的信息 | @author 张三 2015/07/21 |
| @version | @version XX.XX.XX | 描述此函数的版本号 | @version 1.0.3 |
| @example | @example 示例代码 | 演示函数的使用 | @example setTitle('测试') |
~~~dart
/**
* 合并Grid的行
* @param {Grid} grid 需要合并的Grid
* @param {Array} cols 需要合并列的Index(序号)数组;从0开始计数,序号也包含。
* @param {Boolean} isAllSome 是否2个tr的cols必须完成一样才能进行合并。true:完成一样;false(默认):不完全一样
* @return void
* @author polk6 2015/07/21
* @example
* _________________ _________________
* | 年龄 | 姓名 | | 年龄 | 姓名 |
* ----------------- mergeCells(grid,[0]) -----------------
* | 18 | 张三 | => | | 张三 |
* ----------------- - 18 ---------
* | 18 | 王五 | | | 王五 |
* ----------------- -----------------
*/
function mergeCells(grid, cols, isAllSome) {
// Do Something
}
~~~
**不要在循环里面进行DOM操作**
~~~java
//推荐
var htmlString = "";
for(var i =0; i<length;i++){
htmlString += html;
}
$(“.class”).append(htmlString);
//不推荐
for(var i =0; i<length;i++){
$(“.class”).append(html);
}
~~~
**能用CSS实现不用JS实现**
**减少js操作DOM**
在js操作DOM的过程中,要避免频繁改动DOM结构,可以先使用字符串方式组装html代码,再插到DOM结构中去。
**使用事件委托**
* 对于多个同性质同辈节点,避免逐个进行事件绑定。而应该利用冒泡原理,将事件委托给父节点。
* 事件委托要接近事件触发节点,避免将所有事件冒泡委托给body节点
~~~jsx
//推荐
$("table").on("click","td",function(){
})
//不推荐
$("td").on("click",function(){
})
~~~
#### **结语**
**坚持遵循代码规范。**
**写代码前先看看周围同事的代码,然后决定代码风格。**
**代码规范的意义在于提供一个参照物,不会让阅读你代码的人觉得很痛苦。**
*****
主要参考链接
[HTML规范 - 简书 - 辣瓜瓜](https://www.jianshu.com/u/42285a60545e)
[前端开发规范 - codeceo](http://www.codeceo.com/article/google-html-css-style-guide.html)
[前端开发规范 - Google](http://www.chaozh.com/google-front-end-style-guide)
[Javascript开发规范 - Google](http://alloyteam.github.io/JX/doc/specification/google-javascript.xml)
*****
其他参考链接
[PHP开发规范 - W3C](https://www.w3cschool.cn/phpkfbmgf/apedj4.html)
[Java开发规范 - 华为](https://wenku.baidu.com/view/b9533dea647d27284a735199.html)
[Java开发规范 - 阿里巴巴](https://github.com/alibaba/p3c/blob/master/%E9%98%BF%E9%87%8C%E5%B7%B4%E5%B7%B4Java%E5%BC%80%E5%8F%91%E6%89%8B%E5%86%8C%EF%BC%88%E5%8D%8E%E5%B1%B1%E7%89%88%EF%BC%89.pdf)
*****
- 版本控制之Git简介
- Git工作流程
- Git工作区、暂存区、版本库
- Git 指令汇总
- Git 忽略文件规则 .gitignore
- pull request
- HTTP简介
- HTTP - Keep-Alive
- HTTP缓存
- XMLHttpRequest
- Fetch
- 跨域
- HTTP 消息头
- TCP/IP
- TCP首部
- IP首部
- IP 协议
- TCP/IP漫画
- 前端开发规范
- 前端开发规范整理
- 前端未来规划
- HTML思维导图
- CSS思维导图
- 布局
- position,float,display的关系和优先级
- line-height、height、font-size
- 移动端适配
- JS 对象
- JS 原型模式 - 创建对象
- JS 预编译
- 探索JS引擎
- ES