函数组件必须要写name
箭头函数在单参数时口号没有省略

参考AWS资源命名方案：https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html
数据资源（基于MRN进行数据索引）：

命名规范：

一、基础原则

适用范围

适用几乎所有，包括目录名、文件名、类型、变量、函数、常量、命令等。

规范

禁止中文拼音混合、国际不通用中式拼音、甚至直接中文

  • Good✨：luoyang（洛阳） / beijing（北京） / rmb（人民币） / user（用户）

  • Bad😢：pingfen（评分） / setPingfen（设置评分） / a变量 = 1 / 玩具.java

    追求良好的语义化

  • Good✨：demo.js / maxStockCount / drawerRef

  • Bad😢： a.js / m / ref

    二、目录命名

    适用范围

    适用所有目录命名。

    规范

    只要是目录，均采用 kebab-case命名规范：全部小写，多个单词使用单个短横线(-)拼接

  • Good✨：src / scripts / react-dom

  • Bad😢：SRC / Scripts / reactDOM

    目录性质是复数结构时，要采用复数命名法， 缩写不用复数

  • Good✨：components / img / images

  • Bad😢：component / imgs / image

    使用名词，而非动词或者形容词

  • Good✨：manager / user

  • Bad😢：manage / get-user

    三、文件命名

    适用范围

    适用所有源代码文件的命名。

    规范

    对于 class 或者 Component 作为内容默认导出时，采用大驼峰命名规范，单词全部首字母大写，其余小写

  • Good✨：Parent.js / PopperManager.ts / App.tsx

  • Bad😢：parent.js / popper-manager.ts / app.tsx

    对于其它内容文件时，采用 kebab-case 命名规范：全部小写，多个单词使用单个短横线(-)拼接

  • Good✨：config.js / use-custom-hook.ts / user-card.png

  • Bad😢：Config.js / useCustomHook.ts / userCard.png

    不适用上述 2 条规则的特例：

  • README.md

  • LICENSE
  • CHANGELOG
  • index.js 之类的文件

  • main.js 之类的文件

    四、项目命名

    适用范围

    适用于给所有新的业务项目的命名，比如：package.json[name] / git仓库名。

    规范

    格式上建议使用 [scope]-[name]-[client:web|app|miniapp|desktop]

  • scope：表示业务线。采用业务线代码枚举，全部小写，一个单词

附：业务线清单列表：

  • oa 办公自动化
  • hr 人力资源
  • store 商城
  • event 活动
  • community 社区
  • kfs 客服
  • af 售后
  • wms 仓储
  • …（可扩充约定可以随时评论补充特例，评估通过后会添加到文档）
  • name：表示项目具体名称。采用 kebab-case 命名规范：全部小写，多个单词使用单个短横线(-)拼接
  • client：表示端类型。采用枚举，全部小写，多个单词使用单个短横线(-)拼接

附：端类型约定列表：

  • web 表示浏览器端应用。若需细分，可根据渲染类型补充后缀，如下：
    • web-ssr 表示 web 服务端渲染
  • app 表示手机应用。若需细分，可根据系统补充后缀，如下：
    • app-ios 表示仅支持 IOS 端 App
    • app-android 表示仅支持 Android 端 App
  • miniapp 表示小程序应用。若需细分，可根据平台补充后缀，如下：
    • miniapp-wx 表示微信小程序
    • miniapp-tt 表示字节跳动小程序
  • desktop 表示桌面端应用

  • …（可以随时评论补充特例，评估通过后会添加到文档）

    保持一致性，比如 web 前端的 package.json[name] 和 git仓库名 始终一致

  • Good✨：hr-taff-web / oc-okr-web / oc-controller-board-miniapp

  • Bad😢：zhigong_pc / zhigongApp

    五、常量命名

    适用范围

    适用所有地方编码时对常量、枚举属性的定义。

    规范

    定义时力求表达完整，看名知其意

  • Good✨：MAX_USER_CONNECT_COUNT = 0

  • Bad😢：MAX_COUNT = 200

    统一使用下划线大写命名规范：单词字母全大写，使用单个下划线（_）连接

  • Good✨： NODE_ENV \ MAX_USER_CONNECT_COUNT = 0

  • Bad😢：nodeEnvmaxUserConnectCount = 200

    运行时其值始终保持不变

  • Good✨：const NO_ERROR = 200

  • Bad😢：var NO_ERROR = 200; NO_ERROR = 0

注：const 和 var 是 JavaScript 定义变量的语法，这里仅做示例。

枚举属性遵循下划线大写命名规范

  • Good✨：

enum ApiTableErrors { OK = 0, OUT_OF_MEMORY = 1, TIMEOUT = 2 };

六、变量命名

适用范围

适用所有编码时变量取名，包含普通变量、成员属性、函数参数、局部变量等。

规范

统一使用 lower-camel-case命名规范：首个单词首字母小写，其余单词全部首字母大写

  • Good✨：parent / { username: ‘tony’ } / cardBorder
  • Bad😢：Parent / { userName: ‘tony’ } / card_border

    严格使用合适的变量声明，比如 JavaScript 中的 const 和 let 的应用

七、函数命名

适用范围

适用所有编码时对函数取名，包含普通函数、成员函数等。

规范

统一使用 lower-camel-case命名规范：首个单词首字母小写，其余单词全部首字母大写

  • Good✨：open() / { goBack: function () {} } / getUserInfo()
  • Bad😢：Open() / { go_back: function () {} } / userInfo()

    使用 动词 或者 动词 + 名称 的形式

    函数方法常用的动词（可以随时评论补充特例，评估通过后会添加到文档）：
    get 获取 / set 设置
    edit 编辑 / modify 修改
    add 增加 / remove 删除
    insert 插入 / delete 移除
    create 创建 / destory 销毁
    update 更新 / revert 回滚
    find 查找 / search 搜索
    connect 连接 / disconnect 断开
    send 发送 / receive 接收
    download 下载 / upload 上传
    start 开始 / stop 结束
    begin 开始 / end 结束
    open 打开 / close 关闭
    read 读取 / write 写入
    load 加载 / save 保存
    backup 备份 / restore 恢复
    import 导入 / export 导出
    split 分割 / merge 合并
    inject 注入 / extract 提取
    increase 增加 / decrease 减少
    play 播放 / pause 暂停
    encode 编码 / decode 解码
    encrypt 加密 / decrypt 解密
    lock 锁定 / unlock 解锁
    push 推送 / pull 拉取
    enter 进入 / exit 退出
    expand 展开 / collapse 折叠
    observe 观察 / listen 监听
    input 输入 / output 输出
    compile 编译 / execute 执行
    launch 启动 / run 运行
    build 构建 / publish 发布
    pack 打包 / unpack 解包
    parse 解析 / emit 生成
    debug 调试 / trace 跟踪
    view 查看 / browse 浏览
    refresh 刷新 / sync 同步

通用约定注释风格

好的命名固然可以见名知意，但是有时候并不能完整表达代码的功能、目的。而良好的注释让人容易快速理解，并且能够传达上下文关系以及代码目的，从而有效保障代码的可读性。

一、基础原则

适用范围

适用几乎所有，包括文件头、类型、变量、函数、常量、命令等注释声明等。

规范

根据不同语言的注释语法选择使用

注释语法与注释内容需要保留一个空格，多行时对齐

  1. // 我是注释示例 
  2. // 注释内容前面需要有一个空格，并且与代码需要保持对齐 
  3. // 多行注释内容时，注释彼此也需要对齐 
  4. doSomethingElse()

使用完整叙述性句子，注意标点和拼写

表述上尽量言简意赅

  1. /**  * 判断传入的 `value` 是否为空，如果传入的 `value`是空的 object, collection, map 或
  2. * set，则返回 `ture`，否则返回 `false`。  
  3. *   
  4. * @param value 任意类型的值  
  5. * @returns {boolean}  表示是否为空  
  6. */ 
  7. function isEmpty(value: unknown): boolean {
  8.   ... 
  9. }

如上，注释后面就没有必要加上 “否则返回 false”，因为其类型申明已经暗含其中了

二、文件头注释

适用范围

适用所有公开暴露到公网的代码文件，比如：打包后公开的代码文件。

规范

声明公司版权、许可证信息，示例如下：

  1. /** @LICENSE   
  2. * @hi-ui/hiui v4.0.0  
  3. * https://github.com/XiaoMi/hiui#readme  
  4. *  
  5. * Copyright (c) Xiaomi, Inc.  
  6. *  
  7. * This source code is licensed under the MIT license found in the  
  8. * LICENSE file in the root directory of this source tree.   
  9. */

三、函数注释

适用范围

适用所有函数声明。

规范

对于公共方法都需要加上函数注释

对于非公共方法，函数功能简单而明显时，可省略注释

清晰定义函数的目的、功能用途

明确函数使用上的注意事项、可能的隐患

推荐明确函数的输入输出

格式上使用 Jsdoc 规范 https://jsdoc.app/

  1. /**   
  2. * 检查 `value` 是否是空 object，collection，map 或 set。  
  3. *   
  4. * 像 `arguments` 这样的类数组，如果它们的 `length` 属性为 `0` ，也将被视为空的。  
  5. *  
  6. * @since 0.1.0  
  7. * @param {unknown} `value` 要检查的值。  
  8. * @returns {boolean} 如果 `value` 为空则返回 `true`。 
  9. */ 
  10. function isEmpty(value) {   ... }

四、变量注释

适用范围

适用所有变量、常量、枚举、成员属性的声明。

规范

通常变量名函足以说明变量用途，无需注释

说明变量的含义、用途

格式上一般使用 // 我是注释内容 ，采用单行注释

  1. // 库存货物限制的最大数量 
  2. const MAX_STOCK_COUNT = 99

五、实现注释

适用范围

适用代码中实现复杂的、需要描述实现细节的地方加以注释以特殊说明。

规范

复杂的实现细节加以注释，采用单行注释

  1. if (frameDeadline - currentTime <= 0) {   
  2.   // There's no time left in this idle period. Check if the callback has   
  3.   // a timeout and whether it's been exceeded.   
  4.   if (prevTimeoutTime !== -1 && prevTimeoutTime <= currentTime) {     
  5.     // Exceeded the timeout. Invoke the callback even though there's no     
  6.     // time left.     
  7.     didTimeout = true;   
  8.   } else {     
  9.     // No timeout.     
  10.     if (!isAnimationFrameScheduled) {       
  11.       // Schedule another animation callback so we retry later.       
  12.       isAnimationFrameScheduled = true;       
  13.       requestAnimationFrameWithTimeout(animationTick);     
  14.     }     
  15.     // Exit without invoking the callback.     
  16.     scheduledHostCallback = prevScheduledCallback;    
  17.     timeoutTime = prevTimeoutTime;     
  18.     return;   
  19.   } 
  20. }

六、特殊注释（标签）

以下列举的一系列标签注释可以用于任何地方，目的是用来给指定类型的注释打标记，方便查找跟踪。

TODO 注释

适用范围

适用于那些表示功能未完成、待实现的地方。

规范

格式上使用 TODO: $comment

$comment 附上明确的事项，最好有一个非常明确的 deadline

  1. // TODO: 在2022年11月22日前完成 xxx。  
  2. // TODO: 当升级 webpack5 时移除下面这段代码。

FIXME 注释

适用范围

适用于那些表示已经可用但需要改进优化等临时的、短期的解决方案等，需要后续处理的代码。

规范

格式上使用 FIXME: $comment

$comment 附上明确的改进点，并说明应该如何改进优化（如果知道）

  1. // FIXME: 目前该处存在性能瓶颈，可以使用 O(n) 的算法提升其性能。

BUG 注释

适用范围

适用于说明那些临时无法修正，但是必须需要修正甚至代码是错误的，不能工作，需要修复的代码。

规范

格式上使用 BUG: $comment

$comment 附上错误的原因以及会导致的问题，并说明应该如何修正（如果知道）

  1. // BUG: 如果用户输入“复活节”，会始终输出“鸡蛋”，但实际上他们想要一个“兔子”。

DEPRECATED 注释

适用范围

适用于那些某处代码或者函数等已弃用但不能立马删除的场景。

规范

格式上使用 DEPRECATED: $comment

$comment 附上明确的弃用原因、弃用的版本或时间、以及可能推荐的替代品

  1. // DEPRECATED: 在 17.0 版本中删除了 ComponentWillReceiveProps 方法（从该版本开始仅支持使用
  2. 新的 “Unsafe_” 作为前缀命名的生命周期工作）。

HACK 注释

适用范围

适用于某处出现了 trick 奇淫技巧或者骚操作的代码。

规范

格式上使用 HACK: $comment

$comment 附上你所做的 trick 操作及其目的。

  1. // HACK: 直接操作原生 DOM 魔改主题配色，实现部分页面适配最新的 UI 配色规范。

NOTE 注释

适用范围

适用于那些重要的、需要警醒他人的代码场景。

规范

格式上使用 NOTE: $comment

$comment 附上明确注意事项和原因。

  1. // NOTE: 请注意，下面这个路由一定不能删除，要兼容飞书个人卡片中硬编码的 link 跳转。