前端团队命名规范

1,096 阅读8分钟

命名规范


现状

随着团队日益壮大,各自都有自己的不同的编码风格,命名方式风格迥异,为了提高代码易读性,故需统一命名。

  • 黄色表示重要或修订

规范

js &ts & jsx

1、变量

命名方法:小驼峰(Camel)式命名法。 命名规范:前缀应当是名词。(函数的名字前缀为动词,以此区分变量和函数) 命名建议:尽量在变量名字中体现所有类型,

  • 如:length,count等表示数字类型;
  • 而包含name,title等表示字符串类型;
  • boolean类型的建议是用is或has等开头;
  • Promise对象 建议使用动宾短语的进行时表达;
  • 判断是否显示可使用变量:show、visible、hide、hidden等明确性单词
  • res统一规定为response的缩写,result或resource 建议使用全单词
  • table组件数据源建议使用dataSource,与antd组件保持一致,清晰明了,一般一个页面组件只有一个table组件
  • 校验类单词建议使用validated,避免使用check 与 选中 相冲突
  • 避免使用 常用关键字命名变量
  • 接口参数类型声明可添加params表示,返回类型可添加DTO或者首字母大写I开头 等区分
  • 表示状态或类型是建议使用status、state、type等单词
  • 枚举时,文案短或者好描述建议使用小写单词或全大写单词,使用下划线_连接,文案长或不易描述的可使用中文,但禁止在代码中使用数字判断
  • 枚举值 非连续递增关系时,需列举写出每个枚举的值
//good
let maxCount = 10;
let tableTitle = '表格名';
let isReady = false;
let hasMore = false;

let loadingData = ajax.get('url');
loadingData.then(callback)

//bad
let setCount = 10;
let getTitle = '表格名'

枚举变量:使用Pascal命名法,枚举的属性使用全字母大写,单词间下划线分隔的命名方式;

enum DatumAuditStatusConstEnum {
	'WAREHOUSING_PENDING_REVIEW', // 入库待审核
	'WAREHOUSE_ENTRY_AUDIT', // 入库审核中
	'WAREHOUSE_ENTRY_AUDIT_PASSED', // 入库审核通过
	'WAREHOUSE_ENTRY_AUDIT_FAILURE', // 入库审核失败
	'CHANGE_REVIEW_IN_PROGRESS', // 变更审核中
	'CHANGE_REVIEW_SUCCESSFUL', // 变更审核成功
	'CHANGE_AUDIT_FAILURE', // 变更审核失败
}
2、常量

命名方法:名称全部大写 命名规范:使用大写字母和下划线在组合命名,下划线用来分割单词

const MAX_COUNT = 10;
const URL = 'http://www.baidu.com';
const DATE_FORMAT = 'YYYY-MM-DD HH:mm:ss'
3、函数名

命名方法:小驼峰(Camel)式命名法。 命名规范: 前缀应当为动词,建议使用动宾短语 命名建议:可使用常见动词约定,避免使用单字母命名

动词含义返回值
can判断是否可执行某个动作(权限)布尔值,true:可执行;false:不可执行
has判断是否含有某个值布尔值,true:含有;false:不含有
is判断是否为某个值布尔值,true:为某个值;false: 不为某个值
get获取某个值任何值
set设置某个值无返回值
load加载某些数据视场景定
search搜索某些数据视场景定
validate校验、验证某些规则无返回值
query查询某些数据视场景定
add增加、添加数据无返回值
create创建数据无返回值
update更新某个数据无返回值
modify变更某个数据无返回值
edit编辑某个数据无返回值
delete删除某个数据无返回值
initialize初始化某个数据无返回值
select选择某个数据视场景定
cancel取消某个操作无返回值
confirm确认某个操作无返回值
click点击某个元素视场景定
hover移入某个元素视场景定
move移动某个元素视场景定
drag拖动某个元素视场景定
change某个元素或数据改变视场景定

此表格只列举了常规使用的动词,其他场景另行添加适合的动词。

[强制] 区分动作函数和渲染函数,可在动作函数名加handle等前缀,渲染函数名前加前缀render


//查询列表
const handleQueryList = () => {} 

//添加商品
const handleAddGoods = () => {}

//是否可点击
const canClick = ():boolean => {
	return true;
}

// 渲染商品标签
const renderGoodsTag = () => {}

//bad
function q() {
}

函数参数命名参照变量命名法

  • 函数变量至多3个,超过3个使用对象
4、类及其方法/属性 & 构造函数

命名方法:大驼峰式命名法(Pascal),首字母大写 命名规范:建议使用名词

class Person {
	constructor(name){
		this.name = name;
	}
}

const person = new Person('test')

function TextNode(value,name) {
	this.value = value;
	this.name = name;
}
TextNode.protptype.clone = function(){
	return this;
}

类的的成员:

  • 公共属性和方法,参照变量和函数的命名;
  • 私有属性和方法,前缀为_(下划线),后面跟公共属性和方法一样的命名方式
class Person{
	private _name: string;
	constructor(){
		//公共方法
		getName(){
			return this._name;
		}

		setName(name){
			this._name = name;
		}
	}
}

const person = new Person();
person.setName('text');
5、JSX
  • 扩展名:使用.js/.tsx 作为React组件的扩展名;
  • 文件名: 使用Pascal命名法,如MyComponent.js;
  • 组件样式文件命名:统一使用style.less
  • 组件命名: 组件名称和文件名称一致,如MyComponent.js 里的组件名应该是MyComponent; 一个目录的根组件使用index.js命名,以目录名称作为组件名称
  • 当文件夹下仅有一个组件时,文件名与组件名相同;存在多个组件时,添加容器组件index.js/tsx,再在文件夹下创建components,再写单个组件(具体参照项目结构规范
class MyComponent extends Component {}

export default MyComponent;

// bad
import MyComponent from './myComponent'

// good
import MyComponent form './MyComponent'
//bad
import Footer from './Footer/Footer.js';
import Footer form './Footer/index.js';

//good
import Footer form './Footer'
  • 带命名空间的组件 如果一个组件有许多关联子组件,可以以该组件作为命名空间编写,调用子组件
class Row extends Component {}
class Col extends Component{}
class MyComponent extends Component {}
MyComponent.Row = Row;
MyComponent.Col = Col;


const Form = MyComponent;
const App = (
	<Form>
		<Form.Row>
			<Form.Col>
			</Form.Col>
		</Form.Row>
	</Form>
)
  • 属性命名:
    • 组件属性使用小驼峰命名法
    • 使用className 代替 class属性
    • 使用htmlFor代替for属性
    • 传递给 HTML 元素的自定义属性,需要添加 data- 前缀,React 不会渲染非标准属性;
6、其他

由多个单词组成的缩写词,在命名中,根据当前命名法和出现的位置,所有字母的大小写与首字母的大小写保持一致;

function insertHTML(){
}

const httpRequest = new HTTPRequest()

参考 juejin.cn/post/684490… guoyongfeng.github.io/book/21/07-… bitcoin-on-nodejs.ebookchain.org/5-%E9%99%84…

css

1、css文件名:小驼峰式命名法
2、className命名:基于姓氏命名法(继承+外来)
  • 建议尽量精短、明确,全部字母为小写,单词之间统一使用下划线‘_’连接
// 祖先模块不能出现下划线

<div class="list">
	<div class="list_item">
		<div class="list_item_head"></div>
		<div class="listi_tem_body"></div>
		<div class="list_item_footer"></div> 
	</div>
</div>
	
	
  • 在jq或原生开发中,当某个className需作为选择器使用时,建议使用‘js_’开头
<div class="mod_info js_click_box">
    <div class="mod_info_son"></div>
    <div class="mod_info_son"></div>
</div>
  • 全站公共模块:以sys_开头
 <div class="sys_yours"></div>
  • 业务公共模块:以业务名_开头
 <div class="bl_yours"></div>
  • 在子孙模块数量可预测的情况下,严格继承祖先模块的命名前缀
  • 当子孙模块超过4级或以上的时候,可以考虑在祖先模块内具有识辨性的独立缩写作为新的子孙模块
  • 当父级模块单词过多或者过长时 其子孙模块也可以考虑使用缩写,不必局限于超过4级
<div class="modulename">
	<div class="modulename_cover"></div>
	<div class="modulename_info">
    		<div class="modulename_info_user">
    			<div class="modulename_info_user_img">
    				<img src="" alt=""/>
    				<!-- 这个时候 miui 为 modulename_info_user_img 首字母缩写-->
    				<div class="miui_tit"></div>
    				<div class="miui_txt"></div>
   					...
    			</div>
    		</div>
    		<div class="modulename_info_list"></div>
	</div>
</div>
  • 模块化css/less 类目也统一使用该命名方式,多个类名可使用库classnames连接
classNames('foo', 'foo', 'bar'); // => 'foo bar'
classNames('foo', { foo: false, bar: true }); // => 'bar'

  • 变量维护文件统一命名为:variable.less,维护色值和font-size,以及常用的 px规范

  • variable.less:变量命名使用小写单词,以短横线连接。 颜色变量统一以-color结尾,字体大小以-font-size结尾。有些明确能知道设置的是大小,不必加size,如padding-lg

@primary-color: #3ca6fe;
@text-primary-color: fade(#000, 96%);
@text-secondary-color: fade(#000, 72%);
@normal-color: #d9d9d9;

@text-base-font-size: 12px;
@text-lg-font-size: 16px;
@text-md-font-size: 14px;


@padding-lg: 24px; 
@padding-md: 16px; 
@padding-sm: 12px;
@padding-xs: 8px; 
@padding-xss: 4px;

3、 常用命名推荐

注意 :ad、banner、gg、guanggao 等有机会和广告挂勾的字眠不建议直接用来做ClassName,因为有些浏览器插件(Chrome的广告拦截插件等)会直接过滤这些类名

// 这种广告的英文或拼音类名不应该出现
 <div class="ad"></div>
ClassName含义
about关于
account账户
arrow箭头图标
article文章
aside边栏
audio音频
avatar头像
bg,background背景
bar栏(工具类)
branding品牌化
crumb,breadcrumbs面包屑
btn,button按钮
caption标题,说明
category分类
chart图表
clearfix清除浮动
close关闭
col,column
comment评论
community社区
container容器
content内容
copyright版权
current当前态,选中态
default默认
description描述
details细节
disabled不可用
entry文章,博文
error错误
even偶数,常用于多行列表或表格中
fail失败(提示)
feature专题
fewer收起
field用于表单的输入区域
figure
filter筛选
first第一个,常用于列表中
footer页脚
forum论坛
gallery画廊
group模块,清除浮动
header页头
help帮助
hide隐藏
hightlight高亮
home主页
icon图标
info,information信息
last最后一个,常用于列表中
links链接
login登录
logout退出
logo标志
main主体
menu菜单
meta作者、更新时间等信息栏,一般位于标题之下
module模块
more更多(展开)
msg,message消息
nav,navigation导航
next下一页
nub小块
odd奇数,常用于多行列表或表格中
off鼠标离开
on鼠标移过
output输出
pagination分页
pop,popup弹窗
preview预览
previous上一页
primary主要
progress进度条
promotion促销
rcommd,recommendations推荐
reg,register注册
save保存
search搜索
secondary次要
section区块
selected已选
share分享
show显示
sidebar边栏,侧栏
slide幻灯片,图片切换
sort排序
sub次级的,子级的
submit提交
subscribe订阅
subtitle副标题
success成功(提示)
summary摘要
tab标签页
table表格
txt,text文本
thumbnail缩略图
time时间
tips提示
title标题
video视频
wrap容器,包,一般用于最外层
wrapper容器,包,一般用于最外层

参考 guide.aotu.io/docs/name/c… www.jianshu.com/p/98310a24a…