# web_document

**Repository Path**: gjycdd/web_document

## Basic Information

- **Project Name**: web_document
- **Description**: Web前端开发文档
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2018-04-17
- **Last Updated**: 2022-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## Web 前端开发文档

### web_document

#### 作者：gjycdd 时间：2018/4/17

#### author: gjycdd times: 2018/4/17

### 一.规范目的

> * 使开发流程更加规范化，提高写作效率。

### 二.通用规范

| 规范         | 说明                                                                                            |
| :----------- | :---------------------------------------------------------------------------------------------- |
| TAB-SIZE     | 所有的 TAB 使用`2`个空隔代替                                                                    |
| `;`的使用    | `CSS`以及`JAVASCRIPT`语句后都使用`;`方便压缩工具“断句”                                          |
| 文件编码     | 文件内容编码均统一为 UTF-8。                                                                    |
| 中文使用     | CSS、JAVASCRIPT 中的非注释类中文字符须转换成 unicode 编码使用,以避免编码错误时乱码显示。        |
| 文件存放路径 | 静态资源存放于 assets 下，位于 js、css、images、fonts 文件夹下，全局文件放在 utils 下的子目录下 |

### 三.文件夹及文件规范

| 规范       | 说明                                                                                                                                       |
| :--------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| 文件夹     | 使用英文单词命名，多个单词使用驼峰命名                                                                                                     |
| 文件       | 使用英文单词命名，多个单词全部小写并使用连字符`-`进行连接                                                                                  |
| 浏览器拦截 | 一些浏览器会将含有这些词的作为广告拦截，文件命名、ID、CLASS 等所有命名避免以上词汇。ad、ads、adv、banner、sponsor、gg、guangg、guanggao 等 |

### 四.html书写规范

| 规范                 | 说明                                                                                                       |
| :------------------- | :--------------------------------------------------------------------------------------------------------- |
| HTML 属性书写顺序    | 详情见[附录 1](#附录1) HTML 部分                                                                           |
| 标签、属性、属性命名 | 由小写英文、数字和`_`组成，且所有标签必须闭合，属性值必须用双引号`""`,避免使用中文拼音尽量简易并要求语义化 |
| class                | 模块-子模块\_功能-子功能\_\_说明 （最多不超过 5 段）                                                       |
| id                   | 模块-子模块\_功能 （最多不超过 3 段）                                                                      |
| name                 | 模块(首字大写)\_子模块 （最多不超过 2 段）                                                                 |
| 嵌套                 | 避免过多的无意义的`div`嵌套,可以寻求其他元素进行替换                                                       |
| 属性定义             | 确保全部使用`""`进行定义                                                                                   |

> eg: `<div class="banner-item_wrap-avatar__img" id="banner-item_first" name="Banner_first">`

### 五.css书写规范

| 规范                   | 说明                                                                                                                                                                         |
| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 导入所有浏览器支持样式 | `<link rel="stylesheet" type="text/css" href="">`                                                                                                                            |
| 导入所有 IE 支持样式   | `<!--[if IE] <link rel="stylesheet" href=""> <![endif]-->`                                                                                                                   |
| CSS 样式范围           | 全站级、产品级、页面级 （尽量通过继承和层叠重用已有样式，全站级 CSS，改动后，要经过全面测试）                                                                                |
| CSS 书写顺序           | 详情见[附录 1](#附录1) CSS 部分                                                                                                                                              |
| 短选择器的使用         | 使用选择器时，命名比较短的词汇或者缩写的不允许直接定义样式，可以使用父节点限定                                                                                               |
| 多选择器的使用         | 多选择器规则之间换行，即当样式针对多个选择器时每个选择器占一行                                                                                                               |
| z-index 属性           | 尽量 z-index 的值不要超过 150（通用组的除外），页面中的元素内容的 z-index 不能超过 10（提示框等模块除外但维持在 150 以下），最大值为 2048,其余 999-9999 之间的值不可直接使用 |
| 其他注意点             | 见[附录 1](#附录1) 其他                                                                                                                                                      |

### 六.javaScript书写规范

#### 命名规范

| 规范           | 说明                                                              |
| :------------- | :---------------------------------------------------------------- |
| 常量名         | 使用大写英文单词，多个单词使用`_`分隔                             |
| 变量名         | 使用小写英文单词，多个单词使用小驼峰式书写（helloBus）            |
| 私有变量名     | 以`_`开头，使用小写英文单词，多个单词使用小驼峰式书写（helloBus） |
| 对象           | 使用小写`o`开头，以小驼峰式书写（oBus）                           |
| 方法           | 使用小写`f`开头，以小驼峰式书写（fBus）                           |
| 类名（构造器） | 使用小写`c`开头，以大驼峰式书写（CBus）                           |

#### 代码风格

> Eslint 使用 airbnb 部分规范，仅允许`console`和`alert`

| 规范                    | 说明                                                                                                |
| :---------------------- | :-------------------------------------------------------------------------------------------------- |
| ()                      | `()`前后必须使用空格（ES5 方法风格只需在尾部添加空格）                                              |
| 运算符                  | 运算符前后必须使用空格                                                                              |
| ,                       | `,`后需要含有空格（换行除外）                                                                       |
| 条件语句                | 条件语句不能使用简写，必须使用`{}`包装起来                                                          |
| 数组                    | 每一个元素后都需要含有`,`（一行的数组除外）                                                         |
| 对象                    | 键值对以`a: value`形式书写,每个键值对后必须含有`,`                                                  |
| JSON                    | JSON 对象需格式化对象参数                                                                           |
| 字符串                  | 静态字符串使用`''`包裹，字符串拼接使用模板语法（ES6 规则下），ES5-规则采用正常拼接方式 `+` 置于行末 |
| 三目运算                | 不得书写两层以上的三目运算`true ? yep : no`                                                         |
| ===                     | 使用`===`全系列替换`==`全系列避免一些不必要的错误                                                   |
| 判断值                  | null、undefined、null、''、数字 0、NaN 都为 false                                                   |
| new 构造                | 避免使用 new 构造器                                                                                 |
| parseInt                | parseInt 必须显示使用第二个参数以限制进制`parseInt(value, 10)`                                      |
| 字符型布尔值            | 尽量避免'true'\|'false'的写法，如果需要，转为正常布尔值使用`JSON.parse('true'\|'false')`            |
| float 到 integer 的转换 | 使用 Math 函数 floor、ceil、round                                                                   |
| 对象和数组的修改        | 避免直接修改复制后进行修改                                                                          |

### 七.图片规范

| 规范  | 说明                                                                                                                       |
| :---- | :------------------------------------------------------------------------------------------------------------------------- |
| 命名  | 模块\_图片名.图片类型,多个单词以`-`连接                                                                                    |
| 大小  | 图片尽量在[图片压缩](https://tinypng.com/)网站压缩后使用，超过 100K，上传至[图片服务器](https://m.huaqie.com/test/up.html) |
| icons | 小图标推荐使用雪碧图减少服务器请求（不强制）                                                                               |

### 八.模块化规范

| 规范   | 说明                                                                                          |
| :----- | :-------------------------------------------------------------------------------------------- |
| 模块化 | 出现 2 次以上的重复代码考虑模块化，出现 3 次或 3 次以上必须模块化，注意事项见[附录 2](#附录2) |

### 九.注释规范

> 暂定使用 jsdoc 规范，并使用 tj 大神的 dox 作为生成工具

| 规范           | 说明                                                           |
| :------------- | :------------------------------------------------------------- |
| @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       | 函数/类的版本号                                                |

### 附录1

#### html属性顺序

```
  1. class
  2. id 、 name
  3. data-*
  4. src、for、 type、 href
  5. title、alt
  6. aria-*、 role
```

#### css属性顺序

```css
  /* 显示属性 */
    display || visibility
    list-style
    position top || right || bottom || left
    z-index
    clear
    float
  /* 自身属性 */
    width max-width || min-width
    height max-height || min-height
    overflow || clip
    margin
    padding
    outline
    border
    background
  /* 文本属性 */
    color
    font
    text-overflow
    text-align
    text-indent
    line-height
    white-space
    vertical-align
    cursor
    content
```

#### 其他注意点

    不要在标签上直接写样式
    不要在CSS中使用expression
    不要在CSS中使用@import
    不要在CSS中使用!important
    不要在CSS中使用“*”选择符
    不要将CSS样式写为单行
    避免使用filter
    避免使用行内（inline）样式
    避免使用“*”设置{margin: 0; padding: 0;}
    使用after或overflow的方式清浮动

    减少使用影响性能的属性:
    position:absolute;
    float:left;//如这些定位或浮动属性
    减少在CSS中使用滤镜表达式和图片repeat,
    尤其在body当中,渲染性能极差, 如果需要用repeat的话,
    图片的宽或高不能少于8px。

### 附录2

#### html、js模块和 css模块

> html、js 和 css 模块的顶部利用注释写出一下几点

| 注释元素         | 说明                           |
| :--------------- | :----------------------------- |
| 作者             | 表明模块作者说明身份           |
| 时间             | 创建模块的具体时间             |
| 联系方式         | 方便出现问题能够及时联系作者   |
| 版本             | 当前的版本，便于查看对应的文档 |
| 功能说明         | 说明模块的功能、用途           |
| 重大版本修改记录 | 说明本次版本更新的功能         |

> tips：如有大型模块开发，请另起仓库并做好文档书写。