Skip to content

ygwoo/fe-codestyle

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
 
 

Repository files navigation

NWH-BIM中心WEB前端编码风格指南

version 0.8

一、文件命名指南

总体命名规则

坚持所有符号使用一致的命名规则。

冲突项 坚持所有文件名均使用小写命名。

冲突项 坚持所有文件名均使用小驼峰命名。

坚持遵循同一个模式来描述符号的特性和类型,推荐的模式为feature.type.filetype

为什么?

1、命名约定提供了一致的方式来查找内容,让我们一眼就能锁定。 项目的一致性是至关重要的。团队内的一致性也很重要。 2、命名约定帮助我们更快得找到不在手头的代码,更容易理解它。 3、目录名和文件名应该清楚的传递它们的意图。 例如,app/heroes/hero-list.component.ts包含了一个用来管理英雄列表的组件。 4、npm均为小写命名,并使用短横线分割单词,更加的统一和美观且符合现在主流命名习惯。 5、windows文件系统大小写不敏感,而linux文件系统则大小写敏感,为避免生产环境编译发布出现不可预料问题,文件命名使用小写更合适。

使用点和横杠来分隔文件名

坚持遵循先描述文件特性,再描述它的类型的模式,对所有组件使用一致的类型命名规则。推荐的模式为feature.type.filetype

坚持 在描述性名字中,用横杠来分隔单词,即:烤串 (kebab) 命名法。

例如:user-custom.layout.tsx,表示一个自定义用户的react布局组件;user-list.component.vue,表示一个用户列表的vue组件,drag-modal.component.tsx是一个拖拽弹出框的react组件、progress-bar.component.vue是一个Vue进度条组件

坚持使用点来分隔描述性名字和类型,类型名字不要用简写。

坚持使用惯用的后缀来描述类型,包括*.service*.component*.module*.page*.layout*.spec。 必要时可以创建更多类型名,但必须注意,不要创建太多。

比如:

  • service 请求服务
  • component 组件
  • page 页面
  • module 模块
  • layout 布局
  • spec 测试

为什么?

1、类型名字提供一致的方式来快速的识别文件中有什么。 2、利用编辑器或者 IDE 的模糊搜索功能,可以很容易地找到特定文件。 3、像.service这样的没有简写过的类型名字,描述清楚,毫不含糊。 像.srv, .svc, 和 .serv这样的简写可能令人困惑。 4、为自动化任务提供模式匹配。

文件结构指导原则

坚持把所有源代码都放到名为src的目录里。

坚持如果组件/页面具有多个伴隨文件 (.tsx.vue.less.spec),就为它创建一个文件夹。

为什么?

1、在早期阶段能够帮助保持应用的结构小巧且易于维护,这样当应用增长时就容易进化了。 2、组件通常有三个文件 (*.tsx*.less*.vue*.spec.ts),它们很容易把一个目录弄乱。

二、编程约定

总体原则

单一职责

坚持每个文件只定义一样东西(例如服务或组件)。

考虑把文件大小限制在 400 行代码以内。

为什么?

1、单组件文件非常容易阅读、维护,并能防止在版本控制系统里与团队冲突。 2、单组件文件可以防止一些隐蔽的程序缺陷,当把多个组件合写在同一个文件中时,可能造成共享变量、创建意外的闭包,或者与依赖之间产生意外耦合等情况。 3、单独的组件通常是该文件默认的导出,可以用路由器实现按需加载。 4、最关键的是,可以增强代码可重用性和阅读性,减少出错的可能性。

简单函数

坚持定义简单函数

考虑限制在 75 行之内。

为什么?

1、简单函数更易于测试,特别是当它们只做一件事,只为一个目的服务时。 2、简单函数促进代码重用。 3、简单函数更易于阅读。 4、简单函数更易于维护。 5、简单函数可避免易在大函数中产生的隐蔽性错误,例如与外界共享变量、创建意外的闭包或与依赖之间产生意外耦合等

2.1 类

坚持使用大写驼峰命名法来命名类。

例如:class UserComponent优于class userComponent

为什么?

1、遵循类命名传统约定,js构造函数就使用大驼峰命名法。 2、类可以被实例化和构造实例。根据约定,用大写驼峰命名法来标识可构造的东西。

2.2 变量

坚持const声明变量,除非它们的值在应用的生命周期内会发生变化。

考虑少用let声明变量。

坚持小驼峰变量名 (heroRoutes) 比传统的大写蛇形命名法 (HERO_ROUTES) 更容易阅读和理解。

为什么?

1、告诉读者这个值是不可变的。 2、TypeScript 会要求在声明时立即初始化,并阻止再次赋值,以确保达成我们的意图。 3、把常量命名为大写蛇形命名法的传统源于现代 IDE 出现之前, 以便阅读时可以快速发现那些const定义。 TypeScript 本身就能够防止意外赋值。 4、容许现存的const常量沿用大写蛇形命名法。传统的大写蛇形命名法仍然很流行、很普遍,特别是在第三方模块中。 修改它们没多大价值,还会有破坏现有代码和文档的风险。

2.3 接口

坚持使用大写驼峰命名法来命名接口。

考虑不要在接口名字前面加I前缀。

考虑用类代替接口。

为什么?

1、TypeScript 指导原则不建议使用 “I” 前缀。 2、类可以作为接口使用(只是用implements代替extends而已)。

2.4 属性和方法

坚持使用小写驼峰命名法来命名属性和方法。

例如:handleOnClick

避免为私有属性和方法添加下划线前缀。

考虑方法命名使用约定好的动词前缀,例如:getsetaddremove, createdestroystartstop, insertdelete, updatemodify等等。

为什么?

1、遵循传统属性和方法的命名约定。 2、JavaScript 不支持真正的私有属性和方法。TypeScript 工具让识别私有或公有属性和方法变得很简单。

2.5 导入语句中的空行

坚持在第三方导入和应用导入之间留一个空行。

考虑按模块名字的字母顺排列导入行。

考虑在解构表达式中按字母顺序排列导入的东西。

为什么?

1、空行可以让阅读和定位本地导入更加容易。 2、按字母顺序排列可以让阅读和定位本地导入更加容易。

2.6 避免为导入和导出属性、方法、类等指定别名

避免除非有重要目的,否则不要为输入和输出指定别名

例如:import { zip as myzip } from 'lodash,或导出时使用export default class BmpLayoutComponent导入时import BmpLayout from '@/layout/bmp.layout'进行了重命名。

为什么?

同一个属性、类、方法有两个名字(一个对内一个对外)很容易导致混淆。

2.7 成员顺序

坚持把属性成员放在前面,方法成员放在后面。

坚持先放公共成员,再放私有成员,并按照字母顺序排列。

为什么?

把类的成员按照统一的顺序排列,易于阅读,能立即识别出组件的哪个成员服务于何种目的。

2.8 实现生命周期钩子接口

坚持实现生命周期钩子接口,不要写了生命周期钩子函数在组件里,却不实现。

2.9 样式

避免使用通用选择器 *

避免使用元素 id 选择器。

避免使用无具体语义的名字定义的标签选择器。

坚持样式书写统一使用展开格式。

.jdc {

display: block;

width: 50px;

}

坚持样式书写顺序按照:布局方式、位置 > 尺寸 > 文本相关 > 视觉效果

| 布局方式、位置 | display/position/float/top/right/bottom/left/overflow/clear/`z-index |

| -------------- | ------------------------------------------------------------ |

| 尺寸 | width/height/margin/padding/border |

| 文本相关 | font(font-family、font-size、font-style、font-weight、font-varient)/line-height/text-align/vertical-align/text-wrap/text-transform/text-indent/text-decoration/letter-spacing/word-spacing/white-space/text-overflow/word-wrap |

| 视觉效果 | background/color/transition/list-style/cursor/border-radius/box-shadow/text-shadow/transform |

.xxx {
position: absolute; // 布局

width: 100px; // 尺寸

height: 100px;

font-size: 12px; // 文本

line-height: 100px;

text-align: center;

background-color: #f00; // 视觉效果

color: #fff;

}

2.10 注释

坚持为以下情况添加注释:

  • 公共组件使用说明

  • 各组件中重要函数或者类说明

  • 复杂的业务逻辑处理说明

  • 特殊情况的代码处理说明,对于代码中特殊用途的变量、存在临界值、函数中使用的hack、使用了某种算法或思路等需要进行注释描述

  • 单行注释使用//

  • 多重 if 判断语

坚持添加多行注释,推荐格式为:

/**

* 说明

* @关键字

*/

常用注释关键字:(只列出一部分,并不是全部)

| 注释名 | 语法 | 含义 | 示例 |

| -------- | ----------------------------------------- | -------------------- | -------------------------------------------- |

| @param | @param 参数名 {参数类型} 描述信息 | 描述参数的信息 | @param name {String} 传入名称 |

| @return | @return {返回类型} 描述信息 | 描述返回值的信息 | @return {Boolean} true:可执行;false:不可执行 |

| @author | @author 作者信息 [附属信息:如邮箱、日期] | 描述此函数作者的信息 | @author 张三 2015/07/21 |

| @version | @version XX.XX.XX | 描述此函数的版本号 | @version 1.0.3 |

| @example | @example 示例代码 | 演示函数的使用 | @example setTitle('测试') |

参考文档: #JSDoc

三、完善的编辑器配置

坚持在项目中,团队使用统一的.vscode配置文件。

坚持在项目依赖中安装eslinttslintstylelintprettier等代码检查和格式化工具/依赖

About

nwh-fe-codestyle

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published