多应用+插件架构,代码干净,二开方便,首家独创一键云编译技术,文档视频完善,免费商用码云13.8K 广告
### 软件编程规范 在当前软件行业迅猛的发展下,软件逐渐走向大型化。在这种软件走向大型化的形势下,一个软件需要众多的人参与。比如一个操作系统的开发需要上千人的工作。这样我们就不得不面临着如何管理。 只要是一个有用的软件就需要大量的工作,首先要进行[软件需求分析](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) *****