8 策略
8.1 Google 风格未指定的问题:保持一致!
对于本规范未明确解决的任何风格问题,优先按照同一文件中其他代码已有的做法执行。如果这不能解决问题,考虑效仿同一包中的其他文件。
8.2 编译器警告
8.2.1 使用标准警告集
尽可能使用 --warning_level=VERBOSE。
8.2.2 如何处理警告
在做任何事情之前,确保你确切理解警告告诉你什么。如果你不确定为什么会出现警告,请寻求帮助。
一旦你理解了警告,按以下顺序尝试解决方案:
- **首先,修复它或绕过它。**认真尝试实际解决警告,或找到另一种完全避免该情况的方法来完成任务。
- **否则,确定它是否是误报。**如果你确信警告无效且代码实际上是安全和正确的,添加注释来说服读者并应用
@suppress注解。 - 否则,留下 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 重新格式化现有代码
更新现有代码的风格时,请遵循以下指南。
- 不要求更改所有现有代码以满足当前的风格指南。重新格式化现有代码是代码变更和一致性之间的权衡。风格规则随时间演变,这些维护合规性的调整会造成不必要的变更。然而,如果对文件进行了重大更改,则预期该文件将符合 Google 风格。
- 注意不要让机会性的风格修复模糊 CL 的焦点。如果你发现自己做了很多对 CL 的核心焦点不重要的风格更改,请将这些更改提升到单独的 CL 中。
8.4.2 新添加的代码:使用 Google 风格
全新的文件使用 Google 风格,无论同一包中其他文件的风格选择如何。
向不符合 Google 风格的文件添加新代码时,建议首先重新格式化现有代码,遵循 ?? 中的建议。
如果没有进行此重新格式化,则新代码应尽可能与同一文件中的现有代码保持一致,但不得违反风格指南。
8.5 本地风格规则
团队和项目可以采用本文档之外的额外风格规则,但必须接受清理更改可能不遵守这些额外规则,并且不得因为违反任何额外规则而阻止此类清理更改。注意不要制定过多无目的的规则。风格指南不寻求在每种可能的场景中定义风格,你也不应该这样做。
8.6 生成的代码:大部分豁免
构建过程生成的源代码不需要符合 Google 风格。然而,任何将从手写源代码中引用的生成标识符必须遵循命名要求。作为特殊例外,此类标识符允许包含下划线,这可能有助于避免与手写标识符的冲突。