Web前端编码及注释规范

---

一、命名规范

Web前端开发中的命名包括，项目命名、目录命名、JS文件命名、CSS文件命名、HTML文件命名等，详情见链接。详见命名规范

---

二、编码规范

主要包括HTML编码规范、CSS编码规范、JavaScript编码规范。

• HTML编码规范，HTML编码规范主要是对以下几种情形的编码约束：

• 常用HTML语法（代码缩进、属性名命名规则等）
• 页面头部要添加HTML5 doctype标识
• 页面的字符编码要统一使用UTF-8
• 引入CSS、JS的规范
• html元素属性顺序等的规范。
  具体参考：html编码规范

• CSS编码规范，CSS编码规范是对CSS代码的编码约束，主要包括：

• CSS语法
• CSS中分号的使用
• CSS中空格、空行的使用
• class的命名：一个块内的命名要以一个前缀开头，例如与导航相关的命名为nav-XX
• 属性声明的一般顺序
• 有关媒体查询的规范
  具体参考：详细css编码规范

• JavaScript编码规范，JavaScript编码规范主要包括：

• 变量、常量、函数名等的声明位置和命名规范
• 分号的位置和使用（哪些地方必须使用分号）
• 空格、空行、换行的注意点
• 函数的使用注意事项
• 数组、对象的定义规范、书写格式等
• 如何使用null和undefined 等的规范。具体信息参考：JavaScript编码规范

三、注释规范

注释规范主要是对我们所编写代码的注释时机（哪些位置需要注释，哪些情况下需要注释）、注释格式进行约束，包括：HTML的注释、CSS的注释、以及JavaScript的注释。

• HTML注释

HTML页面中要对页面中的每个组件或者区域（例如一个DIV容器）进行注释
格式如： （注意注释符和注释内容之间的空格）
注释快捷键：Ctrl+/
注释行：选中某一行 Ctrl+/ 要与你要注释的代码缩进相同
注释一段代码：选中某一段代码 Ctrl+/

• CSS注释

对于CSS文件要做好三方面注释：

• 文件注释：在文件头部对文件的整体说明
  格式：要写清楚该文件的用途（例如主要定义了哪些样式或者哪个组件的样式）、作者、创建日期、版本（可选）
• CSS文件中对某些关键样式的注释
  格式：在具体css代码块或者代码行的前一行。
• CSS文件中对某一段代码块的注释（例如，某一段代码块专门是为了完成某个组件或者某个效果而编写的）

注意：
CSS注释统一使用：'/* */'
缩进与下一行保持一致
可位于代码行的末尾，与代码间隔一个空格

• JavaScript注释

对于JavaScript代码要做好四方面注释，包括：

• 全局变量及常量的注释：对每个全局变量或者常量进行注释
• 文件注释：在文件头部对文件的整体说明
  格式：要写清楚该文件的用途（例如主要定义了哪些样式或者哪个组件的样式）、作者、创建日期、版本（可选）
• 函数注释：对每个js函数的注释
  格式：要写清楚该函数的功能、每个参数的意义（复杂参数最好举例说明）、返回值（如果有的话）
• 关键代码行的注释：
  具体格式参考：单行注释 多行注释 函数注释

---

附录

Visual Studio Code的使用技巧

快捷键

Ctrl+/ 如果没有注释，则注释，如果已经注释，则取消注释
Shift+Alt+A 注释选中的代码块
Shift+Alt+Up 向上复制一行
Shift+Alt+Down 向下复制一行
Ctrl+U 回退上一个光标
Ctrl+[ /] 代码缩进
Shift+Alt+F 代码格式化

CSS命名规范（列举常用）

• 头：header
  内容：content/container
  尾：footer

导航：nav
侧栏：sidebar
栏目：col
页面外围控制整体布局宽度：wrapper
左右中：left right center
登录条：loginBar
标志：logo
广告：banner
页面主体：main
热点：hot
新闻：news
下载：download
子导航：subNav
菜单：menu
子菜单：subMenu
搜索：search
友情链接：friendLink
页脚：footer
版权：copyright
滚动：scroll
内容：content
标签页：tab
文章列表：list
示信息：msg
小技巧：tips
栏目标题：title
加入：joinus
指南：guide
服务：service
注册：register
状态：status
投票：vote
合作伙伴：partner

ID的命名（列举常用）

• 页面结构
  容器: container
  页头：header
  内容：content/container
  页面主体：main
  页尾：footer
  导航：nav
  侧栏：sidebar
  栏目：col
  页面外围控制整体布局宽度：wrapper
  左右中：left right center
• 导航
  导航：nav
  主导航：mainNav
  子导航：subNav
  顶导航：topNav

边导航：sidebar
左导航：leftSidebar
右导航：rightSidebar
菜单：menu
子菜单：subMenu
标题: title
摘要: summary

• 功能
  标志：logo
  广告：banner
  登陆：login
  登录条：loginBar

注册：register
搜索：search
功能区：shop
标题：title
加入：joinus
状态：status
按钮：btn
滚动：scroll
标签页：tab
文章列表：list
提示信息：msg
当前的: current
小技巧：tips
图标: icon
注释：note
指南：guide
服务：service
热点：hot
新闻：news
下载：download
投票：vote
合作伙伴：partner
友情链接：link
版权：copyright