coding-style - 标准文件

Question

我正在为一个由大约 15 名开发人员组成的团队编写一份编码标准文档，每年的项目负载在 10 到 15 个之间。在其他部分（我可能会在这里发布）中，我正在写一个关于代码格式的部分。因此，首先，我认为无论出于何种原因，我们建立一些基本的、一致的代码格式/命名标准是明智的。

我查看了这个团队在过去 3 年中编写的大约 10 个项目，很明显，我发现了相当广泛的风格。承包商有时进进出出，有时甚至使团队规模扩大一倍。

我正在寻找一些关于代码格式和命名标准的建议，这些建议确实得到了回报……但这也确实是合理的。我认为一致性和共享模式在使代码更易于维护方面大有帮助……但是，在定义上述标准时我还应该考虑其他事情吗？

关于命名空间、打包或源代码文件夹/组织标准的建议呢？我倾向于从以下内容开始：

<com|org|...>.<company>.<app>.<layer>.<function>.ClassName

我很想知道是否还有其他比我习惯的更被接受的做法——在我冒险决定这些标准之前。与已经在线发布的标准的链接也很棒——尽管我已经做了一些。

score 3 · Accepted Answer

首先找到一个适用于您的语言的自动代码格式化程序。原因：无论文件说什么，人们都不可避免地会违反规则。通过格式化程序运行代码比在代码审查中挑剔要容易得多。

如果您使用的是具有现有标准的语言（例如 Java、C#），那么使用它是最容易的，或者至少从它作为初稿开始。Sun 在他们的格式规则上花了很多心思。你不妨利用它。

无论如何，请记住，许多研究表明，大括号位置和空格使用等变化对生产力或可理解性或错误的普遍性没有可衡量的影响。只要有任何标准是关键。

score 3 · Accepted Answer

来自汽车行业，这里有一些用于具体原因的风格标准：

在控制结构中总是使用大括号，并将它们放在不同的行上。这消除了人们在控制结构中添加代码并将其包括或不包括在内的问题。

if(...)
{

}

所有开关/选择都有默认情况。如果它不是有效路径，则默认情况会记录错误。

出于与上述相同的原因，任何 if...elseif... 控制结构必须以默认 else 结尾，如果它不是有效路径，它也会记录错误。单个 if 语句不需要这个。

在循环或控制结构故意为空的偶然情况下，始终会在其中放置分号以表示这是故意的。

while(stillwaiting())
{
   ;
}

命名标准对于 typedef、定义的常量、模块全局变量等有着非常不同的风格。变量名包括类型。您可以查看名称并很好地了解它所属的模块、范围和类型。这使得检测与类型等相关的错误变得容易。

还有其他的，但这些是我最头疼的。

-亚当

score 2 · Accepted Answer

我将同意 Jason 的建议。

我刚刚为一个 10-12 人的团队完成了一份标准文档，该团队主要使用 perl。该文件说要使用“复杂数据结构的类似 perltidy 的缩进”。我们还为每个人提供了示例 perltidy 设置，这些设置将清理他们的代码以满足此标准。该语言非常清晰且非常符合行业标准，因此我们得到了团队的大力支持。

在着手编写此文档时，我四处询问了我们存储库中一些出色代码的示例，并在 Google 上搜索了一些其他标准文档，这些文档比我更聪明的架构师来构建模板。不跨入微观管理者领域，要简洁务实是很难的，但非常值得；有任何标准确实是关键。

希望能成功！

score 1 · Accepted Answer

它显然因语言和技术而异。根据您的示例名称空间，我猜想 java，在这种情况下http://java.sun.com/docs/codeconv/是一个非常好的起点。您可能还想查看 maven 的标准目录结构之类的东西，这将使您的所有项目看起来都相似。

4 回答 4