标准文件

Question

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

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

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

• 括号怎么排列？在处理类、方法、try catch 块、switch 语句、if else 块等时，您是否遵循相同的括号准则？

• 您是否将字段排列在列上？您是否用下划线来标​​记/前缀私有变量？您是否遵循任何命名约定以便更轻松地在文件中查找详细信息？你如何对班级成员进行排序？

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

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

在我冒险规定这些标准之前，我很好奇是否还有其他比我习惯的更容易接受的做法。已经在网上发布的标准的链接也很棒——尽管我已经做了一些。

Answer 1

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

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

无论如何，请记住，大量研究表明，大括号位置和空格使用等不同的因素对生产力、可理解性或错误的流行率没有可测量的影响。只是有 任何 标准是关键。

Answer 2

以下是来自汽车行业的一些风格标准，具体原因如下：

始终在控制结构中使用大括号，并将它们放在单独的行上。这消除了人们在控制结构中错误地添加代码并包含或不包含代码的问题。

if(...)
{

}

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

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

在循环或控制结构故意为空的情况下，总是在其中放置一个分号以表明这是故意的。

while(stillwaiting())
{
   ;
}

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

还有其他的，但这些是我的想法。

-亚当

Answer 3

我将赞同杰森的建议。

我刚刚为一个 10-12 人的团队完成了一份标准文档，该团队主要使用 Perl 工作。该文件说，使用“用于复杂的数据结构的Perltidy样凹痕”。我们还为每个人提供了示例Perltidy设置，这些设置将清理其代码以符合此标准。它非常清晰，并且非常符合该语言的行业标准，因此我们得到了团队的大力支持。

当着手编写这份文档时，我在我们的存储库中询问了一些优秀代码的示例，并在谷歌上进行了一些搜索，找到了比我更聪明的架构师来构建模板的其他标准文档。在不进入微观经理领域的情况下做到简洁和务实是很困难的，但非常值得；拥有 任何 标准确实是关键。

希望一切顺利！

Answer 4

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