本页面介绍了 JavaScript 代码格式化和注释的最佳实践。一致的格式和恰当的注释是代码规范的关键组成部分，它们能显著提高代码的可读性和可维护性。本文档涵盖了何时以及如何统一格式化代码，以及何时需要注释以及什么样的注释是有效的。
有关相关主题，请参阅 变量（关于命名约定）和 函数（关于函数结构指南）。
代码格式和注释是开发者之间的沟通工具。代码主要与计算机交流，而其格式和注释则向其他开发者（包括未来的自己）传达意图和设计决策。
来源： README.md2082-2217 README.md2222-2354
格式很大程度上是主观的，但代码库中的一致性至关重要。《README》明确指出：“不要为格式争论。” 自动化工具应该处理格式化决策，以节省时间并消除不一致之处。
JavaScript 是弱类型语言，因此命名规范为变量、函数和类提供了重要的视觉线索。你选择的具体约定不如一致地应用它重要。
| 类型 | 约定 | 示例 |
|---|---|---|
| 常量 | 全大写 | const DAYS_IN_WEEK = 7; |
| 变量/函数 | 驼峰式命名 | const currentDate = new Date(); |
| 类 | 帕斯卡命名法 | class Animal {} |
| 文件名 | 烤肉串式命名 | clean-code.js |
相互调用的函数应放置在源文件中彼此靠近的位置。理想情况下，调用函数应直接放在被调用函数之上。这符合从上到下的自然阅读模式，从而提高了可读性。
《README》做出了一个大胆的陈述：“注释是作为一种弥补，而非必需。” 这意味着写得好的代码在很大程度上应该是自解释的。只有当代码无法清楚地表达业务逻辑或复杂意图时，注释才是必要的。
《clean code》原则确定了几种注释的反模式
正确的格式和恰当的注释共同作用，创建出更易于维护的代码。它们在代码规范生态系统中服务于不同但互补的目的。
来源： README.md2082-2088 README.md2222-2226
虽然《README》没有规定具体的工具，但它建议尽可能使用自动化来保持格式一致。以下是 JavaScript 项目中常用的工具：
| 工具 | 目的 | 配置 |
|---|---|---|
| ESLint | 代码检查和格式化规则 | .eslintrc 文件 |
| Prettier | 代码格式化 | .prettierrc 文件 |
| StandardJS | 零配置格式化 | package.json 配置项 |
| EditorConfig | 编辑器层面的格式化 | .editorconfig 文件 |
注释应侧重于解释“为什么”，而不是“是什么”。当出现以下情况时，应编写注释：
当出现以下情况时，应避免注释：
《README》展示了命名规范一致性方面的好坏示例。
差
良好
《README》展示了一个哈希函数示例，其中只有非显而易见的部分需要注释。
差
良好
格式化和注释对于编写干净、可维护的 JavaScript 代码至关重要。应尽可能自动化一致的格式化，而注释应明智地使用，以解释复杂的业务逻辑或不明显的意图。请记住，最好的代码需要的注释最少，因为它通过恰当的命名、结构和组织实现了自文档化。
遵循这些指南将有助于创建更易于理解、维护和扩展的代码库——这些都是代码规范的关键特性。