Skip to Content
JavaScript8 策略

8 策略

8.1 Google 风格未指定的问题:保持一致!

对于本规范未明确解决的任何风格问题,优先按照同一文件中其他代码已有的做法执行。如果这不能解决问题,考虑效仿同一包中的其他文件。

8.2 编译器警告

8.2.1 使用标准警告集

尽可能使用 --warning_level=VERBOSE

8.2.2 如何处理警告

在做任何事情之前,确保你确切理解警告告诉你什么。如果你不确定为什么会出现警告,请寻求帮助。

一旦你理解了警告,按以下顺序尝试解决方案:

  1. **首先,修复它或绕过它。**认真尝试实际解决警告,或找到另一种完全避免该情况的方法来完成任务。
  2. **否则,确定它是否是误报。**如果你确信警告无效且代码实际上是安全和正确的,添加注释来说服读者并应用 @suppress 注解。
  3. 否则,留下 TODO 注释。这是最后手段。如果你这样做,**不要抑制警告。**警告应该保持可见,直到它可以被正确处理。

8.2.3 在最窄的合理范围内抑制警告

警告在最窄的合理范围内被抑制,通常是单个局部变量或非常小的方法。通常仅为此目的就提取变量或方法。

示例

/** @suppress {uselessCode} Unrecognized 'use asm' declaration */ function fn() { 'use asm'; return 0; }

即使在一个类中有大量的抑制,也比使整个类对这种类型的警告视而不见要好。

8.3 弃用(Deprecation)

@deprecated 注解标记弃用的方法、类或接口。弃用注释必须包含简单、清晰的指示,告诉人们如何修复其调用位置。

8.4 不符合 Google 风格的代码

你可能偶尔会在代码库中遇到不符合 Google 风格的文件。这些可能来自收购,或在 Google 风格对某些问题做出决定之前编写的,或由于任何其他原因不符合 Google 风格。

8.4.1 重新格式化现有代码

更新现有代码的风格时,请遵循以下指南。

  1. 不要求更改所有现有代码以满足当前的风格指南。重新格式化现有代码是代码变更和一致性之间的权衡。风格规则随时间演变,这些维护合规性的调整会造成不必要的变更。然而,如果对文件进行了重大更改,则预期该文件将符合 Google 风格。
  2. 注意不要让机会性的风格修复模糊 CL 的焦点。如果你发现自己做了很多对 CL 的核心焦点不重要的风格更改,请将这些更改提升到单独的 CL 中。

8.4.2 新添加的代码:使用 Google 风格

全新的文件使用 Google 风格,无论同一包中其他文件的风格选择如何。

向不符合 Google 风格的文件添加新代码时,建议首先重新格式化现有代码,遵循 ?? 中的建议。

如果没有进行此重新格式化,则新代码应尽可能与同一文件中的现有代码保持一致,但不得违反风格指南。

8.5 本地风格规则

团队和项目可以采用本文档之外的额外风格规则,但必须接受清理更改可能不遵守这些额外规则,并且不得因为违反任何额外规则而阻止此类清理更改。注意不要制定过多无目的的规则。风格指南不寻求在每种可能的场景中定义风格,你也不应该这样做。

8.6 生成的代码:大部分豁免

构建过程生成的源代码不需要符合 Google 风格。然而,任何将从手写源代码中引用的生成标识符必须遵循命名要求。作为特殊例外,此类标识符允许包含下划线,这可能有助于避免与手写标识符的冲突。

Last updated on