前端系统开发说明书

《前端系统开发说明书》由会员分享，可在线阅读，更多相关《前端系统开发说明书（12页珍藏版）》请在装配图网上搜索。

1、前端系统开发说明书1. 一般规则应用在HTML, JavaScript 和CSS上的通用规则。1.1. 文件、资源命名?以可读性而言，中划线用来分隔文件名?确保文件命名总是以字母开头而不是数字?特殊含义的文件，需要对文件增加前后缀或特定的扩展名（比如.min.js, .min.css ），抑或一串前缀（比如all.main.min.css ）。使用点分隔符来区分这些在文件名中带有清晰意义的元数据。1.2. 文本缩进一次缩进4个空格。1.3. 代码检查对于前端JavaScript这种比较宽松自由的编程语言来说，严格遵循编码规范和格式化风格指南极为重要。前端开发人员需严格遵循开发规范，并且使用自动

2、代码检查工具（如JSHint ）降低语法错误，确保代码正确执行。JSHint是一款检查JS代码规范与否的工具，用来检查 JS代码的规范性。它提供了配置的 方法，来检查不符合开发规范的错误。1.4. 黄金定律永远遵循同一套编码规范 -可以是这里列岀的，也可以是你自己总结的。不管有多少人共同参与同一项目，一定要确保每一行代码都像是同一个人编写的。2. HTML规范2.1. 文档类型 HTML5 docType使用HTML5的文档类型申明： html5不基于SGML因此不需要对DTD进行引用，但是需要 doctype来规范浏览器的行为（让浏览器 按照他们应该的方式来运行）而 HTML4.01基于SG

3、ML所以需要对 DTD进行引用，才能告知浏览器文档所 使用的文档类型。2.2. media 标签 /禁止数字识自动另 U为电话号码大部分4.75 寸的安卓设备的 viewport 宽设为360px , iPhone 6 上却是375px，大部分5.5 寸 安卓机器（比如说三星 Note ）的viewport 宽为400 , iPhone 6 plus 上是414px。2.3. 语言属性（Language attribute ）强烈建议为html根元素指定lang属性，从而为文档设置正确的语言。这将有助于语音合成工具确 定其所应该采用的发音，有助于翻译工具确定其翻译时所应遵守的规则等等。更多关于

4、lang属性的知识可以从此规范中了解。HTML语言代码参考手册上的文章可以获得更多有用的信息。2.4. 字符编码通过明确声明字符编码，能够确保浏览器快速并容易的判断页面内容的渲染方式。这样做的好处是，可以避免在HTML中使用字符实体标记（character entity ），从而全部与文档编码一致（一般采用UTF-8编码）。2.5. IE兼容模式IE支持通过特定的标签来确定绘制当前页面所应该采用的IE版本。除非有强烈的特殊需求，否则最好是设置为edge mode，从而通知IE采用其所支持的最新的模式。 IE=edge IE=11IE=EmulatelE11IE=10IE=EmulateIE10

5、IE=9IE=EmulatelE9IE=8IE=EmulatelE826注释2.7. 引入 CSS和 JAVASCRIPT根据HTML5规范，在引入 CSS和JavaScript文件时一般不需要指定 type 属性，因为text/css和text/javascript分别是它们的默认值。2.8. 语法2.9. 属性顺序【参考】HTML属性应当按照以下给岀的顺序依次排列，确保代码的易读性。classid, namedata-*src, for, type, hreftitle, altaria-*, roleclass用于标识高度可复用组件，因此应该排在首位。id用于标识具体组件，应当谨慎使用（

6、例如，页面内的书签），因此排在第二位。2.10. 语义化标签根据元素（有时称作“标签”）其被创造出来时的初始意义来使用它 , 有根据有目的地使用 HTML 元 素，对于可访问性、代码重用、代码效率来说意义重大。2.11. 多媒体回溯 :对页面上的媒体而言，像图片、视频、 canvas 动画等，要确保其有可替代的接入接口2.12. 关注点分离 :web中的关注点包括信息（HTML结构）、外观（CSS和行为（JavaScript ）。为了使它们成为可维护 的干净整洁的代码，必须将它们分离开。严格地保证结构、表现、行为三者分离，并使三者之间没有太多 的交互和联系。就是说，尽量在文档和模板中只包含结构

7、性的HTML；而将所有表现代码，移入样式表中；将所有动作行为， 移入脚本中 ;在此之外， 为使得它们之间的联系尽可能的小，在文档和模板中也尽量少地 引入样式和脚本文件。? 合并样式，不引用过多样式表? 合并脚本，不使用过多脚本? 不使用行内样式? 不在元素上使用 style 属性? 不使用行内脚本? 不使用表象元素? 不使用表象 class 名（ red, left, center ）2.13. type 属性省略样式表与脚本上的 type 属性。鉴于 HTML5 中以上两者默认的 type 值就是 text/css 和 text/javascript ，所以 type 属性一般是可以忽略掉的

8、。在老旧版本的浏览器中这么做也是安全可靠的。2.14. ID 和锚点ID 。页面在利用锚点提高用户体验方面，一个比较好的做法是将页面内所有的头部标题元素都加上URL 的 hash 中带上对应的 ID 名称，即形成描点，方便跳转至对应元素所处位置。例如，在浏览器中输入 URL(带有锚点)时，浏览器将定位至锚点对应元素位置。2.15. HTML引号使用双引号(“”)而不是单引号 ()。2.16. 实用为王尽量遵循 HTML 标准和语义，但是不要以牺牲实用性为代价。任何时候都要尽量使用最少的标签并保 持最小的复杂度。3.CSS 规范说明3.1. 文件规范1. 所有文件均归档至约定的目录中：2. 框架

9、引入方式? 外链引入方式? 整包导入项目方式3. 文件引入可通过外联或内联方式引入3.2. CSS注释规范1. 【推荐】文件顶部注释/* description: 中文说明* author ： name* update 2019-01-01 14:00*/2. 模块注释：模块注释必须单独写在一行/* module: module2 by 张三 */Codes/* module: module2 by 张三 */3. 单行注释与多行注释，单行注释可以写在单独一行，也可以写在行尾，注释中的每一行长度不超过40个汉字，或者80个英文字符。4. 特殊注释：用于标注修改、待办等信息/* TODO: xx

10、xx by name 2013-04-13 18:32 */Codes/* BUGFIX: xxxx by name 2012-04-13 18:32 */5. 区块注释/* Header */* Footer */* leftside */3.3. CSS命名规范ID和class（类）名使用可以反应元素目的和用途的名称，或其他通用名称。使用具体且反映元素目的的名称，这些是最容易理解的，而且发生变化的可能性最小。使用连字符（中划线）分隔命名中的单词。为了增强理解性，在选择器中不要使用除了连字符（中划线）以为的任何字符（包括没有）来连接单词和缩写。另外，作为该标准，预设属性选择器能识别连字符（中

11、划线）作为单词attribute|=value 的分隔符。1. 尽可能提高代码模块的复用，样式尽量用组合的方式2. 命名避免使用中文拼音，应该采用更简明有语义的英文单词进行组合，应该用意义命名，而不是 样式显示结果命名；不要用抽象的晦涩的命名.3. 规则命名中，一律采用小写加中划线的方式，不允许使用大写字母或_、不允许通过1、2、3等序号进行命名4. 命名注意缩写，但是不能盲目缩写5. ID命名要注意明确性及唯一性，不要随意新建id6. class命名要注意通用性及复用性，命名必须言简意赅7. 避免class 与id重名3.4. 声明顺序1. Positioning 定位：可以使一个元素脱离正

12、常文本流，并且覆盖盒模型相关的样式2. Box model盒模型：决定了一个组件的大小和位置3. Typographic 排版：4. Visual 外观：3.5. CSS代码格式排版规范?使用4个空格，而不使用tab或者混用空格+tab作为缩进?规则可以写成单行，或者多行，但是整个文件内的规则排版必须统一?多个selector共用一个样式集，则多个 selector必须写成多行形式；?每一条规则结束的大括号必须与规则选择器的第一个字符对齐；?写成单行时每一条规则的大括号前后加空格，每一条规则结束的大括号前加空格；?属性名冒号之前不加空格，冒号之后加空格；?每一个属性值后必须添加分号；并且分号后

13、空格；规则书写规范?使用单引号，不允许使用双引号；?除16进制颜色和字体设置外， CSS文件中的所有的代码都应该小写 ；?除了重置浏览器默认样式外，禁止直接为html tag添加css样式设置；?每一条规则应该确保选择器唯一，禁止直接为全局 .nav、.header、.body等类设置属性；代码性能优化?合并 margin、padding、border 的-left/-top/-right/-bottom的设置，尽量使用短名称。?选择器应该在满足功能的基础上尽量简短，减少选择器嵌套，查询消耗。但是一定要避免覆盖全局样式设置。?注意选择器的性能，不要使用低性能的选择器。?禁止在css中使用*选择

14、符。除非必须，否则，一般有class或id的，不需要再写上元素对应的tag?0后面不需要单位，比如Opx可以省略成0, 0.8px可以省略成.8px。?如果是16进制表示颜色，则颜色取值应该大写， 如果可以，颜色尽量用三位字符表示,例女口 #AABBC(写成 #ABC。?如果没有边框时，不要写成 border:。，应该写成border:none 。?尽量避免使用 AlphalmageLoader?在保持代码解耦的前提下，尽量合并重复的样式。?background、font等可以缩写的属性，尽量使用缩写形式。CSS Hack的使用请不用动不动就使用浏览器检测和CSS Hacks，先试试别的解决方

15、法吧！考虑到代码高效率和易管理，虽然这两种方法能快速解决浏览器解析差异，但应被视为最后的手段。在长期的项目中，允许使用hack只会带来更多的hack，你越是使用它，你越是会依赖它！区别属性：IE6 - _property:value IE6/7 - *property:value IE6/7/8/9 -property:value9区别规则：IE6 - * html select . IE7 - *:fist-child+html selector .非 IE6 - htmlbody selector . firefox only - -moz-document url-prefix().字体

16、规则为了防止文件合并及编码转换时造成问题，建议将样式中文字体名字改成对应的英文名字，如：黑体(SimHei) 宋体(SimSun)微软雅黑(Microsoft Yahei，几个单词中间有空格组成的必须加引号)为了对font-family取值进行统一，更好的支持各个操作系统上各个浏览器的兼容性，font-family不允许在业务代码中随意设置3.6. CSS编码技巧1. 尽量减少代码重复2. 合理使用简写3. 是否应该使用预处理器?4. 层级（z-index）必须清晰明确，页面弹窗、气泡为最高级（最高级为999）,不同弹窗气泡之间可在三位数之间调整；普通区块为10-90内10的倍数；区块展开、弹

17、出为当前父层级上个位增加，禁止层级间盲目攀比。4. JS规范4.1. JS文件规范?文件编码统一 UTF-8;?消除Javascript 语法的一些不合理、不严谨之处，减少一些怪异行为；?消除代码运行的一些不安全之处，保证代码运行的安全；?提高编译器效率，增加运行速度?为未来新版本的Javascript做好铺垫4.2. JS注释规约1. 类，类属性，类方法使用/*内容*/格式，不得使用/ xxx 方式2. 方法内部单行注释，在被注释语句上方另起一行，使用/注释。方法内部多行注释使用/* */注释,注意与代码对齐。3. 代码修改同时，注释也要进行相应修改，尤其是参数、返回值、核心逻辑等的修改。说

18、明：代码 与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导 航的意义。4. 谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除；说明：代码被注释掉有两种可能性：1）后续会恢复此段代码逻辑。2 ）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。5. 对于注释的要求：?第一、能够准确反应设计思想和代码逻辑?第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够

19、快速接替自己的工作。好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免岀现注释的一个极端：过多过滥的 注释，代码的逻辑一旦修改，修改注释是相当大的负担特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。 线上故障有时候就是来源于这些标记处的代码。?待办事宜（TODO :（标记人，标记时间，预计处理时间）表示需要实现，但目前还未实现的功能。?错误，不能工作（FIXME :（标记人，标记时间，预计处理时间）在注释中用FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。43 JS命名规范1. 文件夹统一使用全小写2. 代码中命名不能以下

20、划线或美元符开始，也不能以下划线或美元符结束3. 代码中严禁使用拼音与英文混合的方式，更不允许直接使用中文方式。纯拼音命名方式也要避免采用（国际通用的名称可视为英文，如：taobao，alibaba等）4. 类名使用UpperCamelCase风格5. 方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格，必须遵从驼峰形式如:localValue ， getMessage（）6. 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长7. 杜绝完全不规范的缩写，避免望文不知义8. 为了达到代码自解释的目标，任何定义编程元素在命名时使用尽量完整单词组合来

21、表达其意4.4. JS代码风格规范1. 大括号使用约定：如果大括号内容为空则简洁的写成 即可，不需要换行；如果非空代码块则:?左大括号前不换行?左大括号后换行?右大括号前换行?右大括号后还有else等代码则不换行左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格（见下例）任何二目、三目运算符的左右两边都需要加一个空格；如：settings = settings ? settings : ; if (a& flag = 1) 注释的双斜线与注释内容之间有且仅有一个空格；如如： /注释内容，注意在/和注释内容之间有一个空格单行字符数限不超过120个，超岀需要换行，超岀需要换行时遵循

22、如下原则：?第二行相对第一行缩进4空格，从第三行开始，不再继续缩进?运算符与下文一起换行?方法调用是，多个参数需要换行时，在逗号后进行?在括号前不要换行方法参数在定义和传入是，多个参数逗号后面加空格；如：Function Sum(a, b, c) Sum(1,2, 3);4.5. JS常量定义规范1. 不允许任何魔法值(即未经定义的常量)直接岀现在代码中2. 不要使用一个常量类维护所有常量，按常量功能进行归类，分开维护3. 常量复用层次，公共常量、模块常量、功能页面常量4.6. JS控制语句规范1. 在一个switch块内，每个case要么通过break、return等来终止，要么注释说明程序

23、将继续执 行到哪一个case为止；在一个switch块内，都必须包含一个 default语句，并且放在最后，即 是他什么代码也没有。2. 在if/else/for/while/do语句中必须使用大括号。即使只有一行代码，避免采用单行的编码方式:if (condition) statements;3. 表达异常的分支时，少用if-else 方式，这种方式可以改写成，如果非得使用避免后续代码维护 困难，请勿超过3层。4. 不要在条件判断中执行其它复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性(很多if语句内的逻辑相当复杂，阅读者需要分析条件表达式的最终结果，才能明 确什么样的条件执行什么样的语句，那么，如果阅读者分析逻辑表达式错误呢？5. 循环体中的语句要考量性能