My-Notes

001.Web前端开发规范（1）——通用规范

10分钟阅读

一、规范目的

  • 提高代码质量
  • 使开发流程更加规范化。
  • 增强团队的开发协作效率
  • 便于后期优化维护
  • 便于后台人员添加功能

二、通用规范

以下章节列举了一些可应用在 HTML, JavaScript 和 CSS 上的通用规则。

2.1 文件/资源命名

文件名全部使用小写字母，用短横线（减号）分隔单词，其中**不得包含汉字、空格和除""或”_“)开头命名的文件，一般都有特殊的含义与用处（比如 compass[1] 中的下划线就是用来标记跳过直接编译的文件用的）。 还有一些情况下，需要对文件增加前后缀或特定的扩展名（比如：.min.js，.min.css），抑或一串前缀（比如：3fa89b.main.min.css）。这种情况下，建议使用点分隔符来区分这些在文件名中带有清晰意义的元数据。 文件夹命名同理。

命名原则的指导思想：

  • 一是使得你自己和工作组的每一个成员能够方便的理解每一个文件的意义；
  • 二是当我们在文件夹中使用“按名称排例”的命令时，同一种大类的文件能够排列在一起，以便我们查找、修改、替换、计算负载量等等操作。

正确示例：

buckminster-fuller.html
my-script.js
my-camel-case-name.css
i-love-underscores.html
thousand-and-one-scripts.js
my-file.min.css

错误示例：

Buckminster_Fuller.html（错误原因：使用大写字母，用下划线分割单词）
MyScript.js（错误原因：使用大写字母，未用短横线分割单词）
myCamelCaseName.css（错误原因：使用大写字母，未用短横线分割单词）
i_love_underscores.html（错误原因：使用下划线分割单词，未用短横线分割单词）
1001-scripts.js（错误原因：文件名以数字开头）
my-file-min.css（错误原因：my-file和min无语义联系，".min.css"代表“压缩格式的css”）

a. HTML 的命名原则

引文件统一使用 index.html index.php index.asp 文件名； 各子页命名的原则首先应该以栏目名的英语翻译取单一单词为名称。例如：

  • 关于我们 \ aboutus
  • 信息反馈 \ feedback
  • 产品 \ product

如果栏目名称多而复杂并不好以英文单词命名，则统一使用该栏目名称拼音或拼音的首字母表示； 每一个目录中应该包含一个缺省的 html 文件，文件名统一用 index.html index.php index.asp；

b. 图片的命名原则

图片的名称分为头尾两部分，用下划线隔开； 头部分表示此图片的大类性质，例如：广告、标志、菜单、按钮等等。

  • 放置在页面顶部的广告、装饰图案等长方形的图片取名：banner
  • 标志性的图片取名：logo
  • 在页面上位置不固定并且带有链接的小图片取名：button
  • 在页面上某一个位置连续出现，性质相同的链接栏目的图片取名：menu
  • 装饰用的照片取名：pic
  • 不带链接表示标题的图片取名：title
  • 图标图片取名：icon

范例：banner_sohu.gif menu_aboutus.gif title_news.gif logo_police.gif pic_people.jpg icon_back.png 鼠标感应效果图片命名规范为”图片名+_+on/off”。 例如：button_``search``_on.gif button_``search``_off.gif

2.2 目录结构

_Root/                    ——根目录
├── index.html            ——首页
├── favicon.ico            ——网站图标
├── pages/                ——网页文件
│   ├── aboutus/
│   │   └── aboutus.html
│   ├── product/
│   ├── feedback/
│   │   └── feedback.php
├── css/                    ——CSS文件
│   ├── style.css
│   ├── style.css.map
│   └── style.min.css
├── js/                    ——JavaScript脚本
│   ├── main.js
│   └── main.min.js
├── images/                ——图片文件
│   ├── logo_police.png
│   └── menu_aboutus.gif
├── fonts/                ——字体文件
│   ├── fontr.eot
│   ├── font.svg
│   ├── font.ttf
│   ├── font.woff
│   └── font.woff2
├── library/                ——第三方库
│   └── bootstrap/
├── project/                ——工程项目资料
└── temp/                    ——临时文件

2.3 协议

不要指定引入资源所带的具体协议。 当引入图片或其他媒体文件，还有样式和脚本时，URLs 所指向的具体路径，不要指定协议部分（http:，https:），除非这两者协议都不可用。 不指定协议使得 URL 从绝对的获取路径转变为相对的，在请求资源协议无法确定时非常好用，而且还能为文件大小节省几个字节。

不推荐：

<script src="http://cdn.com/foundation.min.js"></script>
.example {
    background: url(http://static.example.com/images/bg.jpg);
}

推荐：

<script src="//cdn.com/foundation.min.js"></script>
.example {
    background: url(//static.example.com/images/bg.jpg);
}

2.4 图片

  1. 遵循图片的命名原则
  2. 所有页面元素类图片均放入 images 文件夹, 测试用图放于 images/testimg 文件夹，psd 源图放入 images/psdimg 文件夹；
  3. 图片格式仅限于 gif、png、jpg；
  4. 在保证视觉效果的情况下选择最小的图片格式与图片质量, 以减少加载时间；
  5. 尽量避免使用半透明的 png 图片 (若使用, 请参考 css 规范相关说明)；
  6. 运用 css sprite 技术集中小的背景图或图标，减小页面 http 请求；但注意，请务必在对应的 sprite psd 源图中划参考线，并保存至 img 目录下。

2.5 文本缩进

一次缩进两个空格。 TAB 键用两个空格代替（WINDOWS 下 TAB 键占四个空格，LINUX 下 TAB 键占八个空格）。

2.6 注释

注释是你自己与你的小伙伴们了解代码写法和目的的唯一途径。特别是在写一些看似琐碎的无关紧要的代码时，由于记忆点不深刻，注释就变得尤为重要了。 代码注释，则是永远也不嫌多。 JS、CSS 文件注释需要标明作者、文件版本、创建/修改时间、重大版本修改记录、函数描述、文件版本、创建或者修改时间、功能、作者等信息。 /* * 注释块 */ 中间可添加如下信息：

@file 文件名
@addon 把一个函数标记为另一个函数的扩张，另一个函数的定义不在源文件中
@argument 用大括号中的自变量类型描述一个自变量
@author 函数/类作者的姓名
@base 如果类是继承得来，定义提供的类名称
@class 用来给一个类提供描述，不能用于构造器的文档中
@constructor 描述一个类的构造器
@deprecated 表示函数/类已被忽略
@exception 描述函数/类产生的一个错误
@exec @extends 表示派生出当前类的另一个类
@fileoverview 表示文档块将用于描述当前文件，这个标签应该放在其它任何标签之前
@final 指出函数/类
@ignore 让jsdoc忽视随后的代码
@link 类似于@link标签，用于连接许多其它页面
@member 定义随后的函数为提供的类名称的一个成员
@param 用大括号中的参数类型描述一个参数
@private 表示函数/类为私有，不应包含在生成的文档中
@requires 表示需要另一个函数/类
@return 描述一个函数的返回值
@see 连接到另一个函数/类
@throws 描述函数/类可能产生的错误
@type 指定函数/成员的返回类型
@version 函数/类的版本号

当你写注释时一定要注意：不要写你的代码都干了些什么，而要写你的代码为什么要这么写，背后的考量是什么。当然也可以加入所思考问题或是解决方案的链接地址。

下启：002.Web前端开发规范（2）——代码规范

反向链接

关系图谱