写点什么

代码风格与编码习惯

作者:yuanyxh
  • 2024-09-14
    中国香港
  • 本文字数:3352 字

    阅读完需:约 11 分钟

代码风格与编码习惯

代码风格

变量、函数 の 命名

a_zA_Z_$、数字组成, 以 a_zA_Z_$ 开头,小驼峰式命名,命名要有意义,不可以使用关键词或保留字。

变量

可变的数据,预先声明,变量类型应始终如一。

常量

不变的数据,预先声明,常量名称字母全部大写,多个单词以 _ 分隔。

函数

实现一个或多个功能的代码块,接收给定的参数返回对应的输出,当输出因为内部实现可能有多种格式时,应规整化输出;函数应尽可能的轻,当一个函数过于臃肿时应考虑重新设计,并分离为多个小函数,通过组合的方式实现复杂的逻辑。


构造函数的函数名开头应大写。

代码嵌套

当代码嵌套过深时应考虑重新设计代码结构,包括抽离函数,代码反转等,具体看 为什么你不应该嵌套代码

注释

对于自定义的数据而言,需要标注他的作用,可选的,你可以注释其他你想让其他开发者知道的信息;对于复杂的代码逻辑,需要清楚的标注它的功能。

注解

对文件、代码进行注解,文件注解:作者、版权等,代码注解如:类型注解、细节注解(TODO: 有功能待实现,对将要实现的功能进行简单说明 FIXME: 代码运行正常,但需要修正)等。


注解有关资料看:


编码习惯

缩进

同一个代码块的代码行在换行时应进行缩进,每行代码超过 80 个字符(常见)时应考虑换行。

内存

一个长时间在内存中的对象在不需要使用时应手动进行销毁,如闭包;避免创建生命周期极短的对象(创建并立即销毁的对象会触发垃圾清理机制)。

vscode 插件推荐

KoroFileHeader

快速生成文件、函数的注解,插件配置:koro1FileHeader


部分配置说明:


// 头部注释"fileheader.customMade": {    // 头部注释默认字段    "Author": "your name",    "Date": "Do not edit", // 设置后默认设置文件生成时间    "LastEditTime": "Do not edit", // 设置后,保存文件更改默认更新最后编辑时间    "LastEditors": "your name", // 设置后,保存文件更改默认更新最后编辑人    "Description": "",    "FilePath": "Do not edit", // 设置后,默认生成文件相对于项目的路径    "custom_string_obkoro1": "可以输入预定的版权声明、个性签名、空行等"},// 函数注释"fileheader.cursorMode": {  // 默认字段  "description":"",  "param":"",  "return":""},// 插件配置项"fileheader.configObj": {  "autoAdd": true, // 检测文件没有头部注释,自动添加文件头部注释  "autoAddLine": 100, // 文件超过多少行数 不再自动添加头部注释  "autoAlready": true, // 只添加插件支持的语言以及用户通过`language`选项自定义的注释  "supportAutoLanguage": [], // 设置之后,在数组内的文件才支持自动添加  // 自动添加头部注释黑名单  "prohibitAutoAdd": [    "json"  ],  "prohibitItemAutoAdd": [ "项目的全称禁止项目自动添加头部注释, 使用快捷键自行添加" ],  "folderBlacklist": [ "node_modules" ], // 文件夹或文件名禁止自动添加头部注释  "wideSame": false, // 头部注释等宽设置  "wideNum": 13,  // 头部注释字段长度 默认为13  "functionWideNum": 0, // 函数注释等宽设置 设为0 即为关闭  // 头部注释第几行插入  "headInsertLine": {    "php": 2 // php文件 插入到第二行  },  "beforeAnnotation": {}, // 头部注释之前插入内容  "afterAnnotation": {}, // 头部注释之后插入内容  "specialOptions": {}, // 特殊字段自定义  "switch": {    "newlineAddAnnotation": true // 默认遇到换行符(\r\n \n \r)添加注释符号  },  "moveCursor": true, // 自动移动光标到Description所在行  "dateFormat": "YYYY-MM-DD HH:mm:ss",  "atSymbol": ["@", "@"], // 更改所有文件的自定义注释中的@符号  "atSymbolObj": {}, //  更改单独语言/文件的@  "colon": [": ", ": "], // 更改所有文件的注释冒号  "colonObj": {}, //  更改单独语言/文件的冒号  "filePathColon": "路径分隔符替换", // 默认值: mac: / window是: \  "showErrorMessage": false, // 是否显示插件错误通知 用于debugger  "writeLog": false, // 错误日志生成  "CheckFileChange": false, // 单个文件保存时进行diff检查  "createHeader": true, // 新建文件自动添加头部注释  "useWorker": false, // 是否使用工作区设置  "designAddHead": false, // 添加注释图案时添加头部注释  "headDesignName": "random", // 图案注释使用哪个图案  "headDesign": false, // 是否使用图案注释替换头部注释  // 自定义配置是否在函数内生成注释 不同文件类型和语言类型  "cursorModeInternalAll": {}, // 默认为false 在函数外生成函数注释  "openFunctionParamsCheck": true, // 开启关闭自动提取添加函数参数  "functionParamsShape": ["{", "}"], // 函数参数外形自定义  // "functionParamsShape": "no type" 函数参数不需要类型  "functionBlankSpaceAll": {}, // 函数注释空格缩进 默认为空对象 默认值为0 不缩进  "functionTypeSymbol": "*", // 参数没有类型时的默认值  "typeParamOrder": "type param", // 参数类型 和 参数的位置自定义  // 自定义语言注释,自定义取消 head、end 部分  // 不设置自定义配置language无效 默认都有head、end  "customHasHeadEnd": {}, // "cancel head and function" | "cancel head" | "cancel function"  "throttleTime": 60000, // 对同一个文件 需要过1分钟再次修改文件并保存才会更新注释    // 自定义语言注释符号,覆盖插件的注释格式  "language": {    // js后缀文件    "js": {      "head": "/$$",      "middle": " $ @",      "end": " $/",      // 函数自定义注释符号:如果有此配置 会默认使用      "functionSymbol": {        "head": "/******* ", // 统一增加几个*号        "middle": " * @",        "end": " */"      },      "functionParams": "typescript" // 函数注释使用ts语言的解析逻辑    },    // 一次匹配多种文件后缀文件 不用重复设置    "h/hpp/cpp": {      "head": "/*** ", // 统一增加几个*号      "middle": " * @",      "end": " */"    },    // 针对有特殊要求的文件如:test.blade.php    "blade.php":{      "head": "<!--",      "middle": " * @",      "end": "-->",    }  }, // 默认注释  没有匹配到注释符号的时候使用。 "annotationStr": {    "head": "/*",    "middle": " * @",    "end": " */",    "use": false  }}
复制代码

TODO Highlight

TODO Highlight 设置对应注解的高亮,默认配置有 TODO:FIXME:,如下:


/** * TODO: 这是一个未完成的函数,功能是 AI 自动写项目 */function autoComplete(demand) {}
/** * FIXME: 这是一个有问题的函数,待修正 */function saiHi() { console.log('hello');}
复制代码


也可以自定义关键词,具体配置看 TODO Highlight

EditorConfig for VS Code

多人开发时可能使用不同的编辑器,EditorConfig 用于统一项目的编码格式,这个插件用于在 vscode 中识别对应配置,常用配置:


.editorconfig file


# EditorConfig is awesome: https://EditorConfig.org
# top-most EditorConfig file
root = true
# Unix-style newlines with a newline ending every file
[*]charset = utf-8indent_style = spaceindent_size = 2end_of_line = lftrim_trailing_whitespace = trueinsert_final_newline = true
[*.md]max_line_length = offtrim_trailing_whitespace = false
复制代码


其他配置看 editorconfig

ESLint

代码检查,配合 eslint 包使用,在编码时发现不合理的代码。官网 eslint

Prettier - Code formatter

格式化工具,对代码进行指定配置的格式化,相关配置可看 prettier-vscode


也可在项目中使用 prettier 包对整个项目进行格式化,安装 prettier 并在项目中添加 "prettier": "prettier --write ." 命令,运行即可。


项目中新建 .prettierrc 可设置格式化的配置,常用配置


{  "useTabs": false,  "tabWidth": 2,  "printWidth": 80,  "singleQuote": true,  "semi": true,  "trailingComma": "none"}
复制代码


更多配置看 prettier


.prettierignore 文件设置忽略文件,写法与 .gitignore 相同。


发布于: 刚刚阅读数: 5
用户头像

yuanyxh

关注

站在巨人的肩膀上 2023-08-19 加入

web development

评论

发布
暂无评论
代码风格与编码习惯_js_yuanyxh_InfoQ写作社区