Question

编码指南的一些很好的例子。我并不是真的想找一种特定于单一语言的东西。

但在编写编码指南时，我应该做什么/评估？比如指南应该有多灵活，应该给程序员或其他人留下多少决定，甚至是指南预先决定的。

我正在制定的这套指南应涵盖广泛的主题：评论，数据库设计，甚至一些用户界面指南。

Answer 1

编码标准通常有三个目的：

降低错误的可能性
减少分析其他人编写的代码所需的时间
给某人一个权力之旅

显然，第三种是浪费其他人的时间，但你确实需要考虑它，特别是你不走这条路。

话虽如此，我已经注意到了一些确定的事情，并且没有。

实施一致的空白用法。标签，2个空格，4个空格，无所谓。保持一致，因此使用不同编辑器的人不会搞砸缩进级别。我看到了错误，因为维护程序员误解了代码块的嵌套级别。
实施一致的日志记录方法。如果他们无法浏览日志，这会大大消耗支持人员的时间，因为每个人的模块都会出于不同的原因记录，并且每个人都有不同的信息与警告与错误的定义。
实施一致的错误处理。如果模块A抛出异常，模块B返回错误代码，模块C只是记录并继续前进，将它们集成在一起并不让错误滑过裂缝将是一件痛苦的事。
尽量避免像花括号那样的小事。这会让很多人争论他们的宠物风格，最终，它对代码的可读性没有太大的影响。另一方面，强制执行括号的存在会产生影响。
在集成不同的代码库时，不要试图改变每个人的变量命名约定以匹配黄金标准。您可能有前进的标准，但最重要的是，已经存在的任何本地化标准都会保持一致。如果一个模块使用m_member，则维护程序员应该使用m_member2而不是应用任何其他标准（例如member2_或m_lpcstrMember2或其他）。本地一致性是王道。
文件系统布局很重要。保持一致。让某人很容易跳进库源库并立即知道头文件，Makefile，源代码等等。如果你正在使用Java或Python，这是一个明智的选择因为包系统强制执行它。如果你正在使用C，C ++或任何其他无数的脚本语言，你需要自己设计一个标准的布局并坚持下去。
不要为小东西出汗。变量命名约定，括号或关键字或函数名之间的空格......大多数都无关紧要，因为它不会降低错误的可能性。你设定的每条规则都应该有一个具体的理由，如果你发现它引起的更多的悲伤，你不应该害怕改变或删除它。
不要在任何地方强制执行无偿评论。它们最终会成为浪费，大多数注释最好不要在代码本身中表达（例如，作为变量或函数名称）。

最后，最重要的是在同行之间进行定期的代码审查。鼓励人们在看到“代码味道”时说出来。还要确保人们意识到建设性的代码批评并不是个人的 - 来源是团队中永远的共享，它不仅仅属于原作者。根据我的经验，最令人发指的问题是任何编码指南都无法解决的设计问题。软件设计仍然是一种艺术形式（无论好坏），而且一大脑比一个大脑要好得多。

Answer 2

if( !codingGuidelines.Followed)
{
   reason = programmer.WhyNot();
   if( reason.Acceptable)
   {
      codingGuidelines.Integrate( reason);
   }
   else
   {
      team.GiveAssKicking(programmer);
   }
}

Answer 3

这是一个相当开放的问题，答案同样公开：

每项指南的实施成本都应低于其带来的好处。

要小心，因为等式的每一边都有一些隐藏的部分。

实施成本可以包括排除完美的替代品，扼杀创新和创新，并鼓励代码审查堕落，突出显示风格的轻微违规，而不是解决实际问题。

对于忙碌的开发人员来说，收益的价值可能是无形的（因而令人沮丧），但可能会导致您的组织品牌变得更强大或者让新员工更快地加入项目 - 这可能会超过小额增量遵守的成本。

Answer 4

作为一名开发人员，我通常更喜欢指导方针来提供基本指导，但不要太严格以至于我无法编码我喜欢的代码...例如，如果指南告诉我必须使用哪种编码模式而不是允许我做出自己的专业判断然后它太紧张了：

例如，这些是我可能期望看到的类型：

变量名称的样式，即匈牙利表示法（不是我严格使用那些）
方法应该用它们的一般目的来评论，包括它们返回的内容（如果有的话）
应使用特定布局定义类：即顶部的所有私有字段，后跟事件，公共方法，私有方法，是否应按字母顺序排列
命名空间，类，方法，事件和属性等的命名约定

你得到了照片。我不应该局限于：

你应该使用If notation而不是int a =（blah）？ true：false;

编码样式显然需要在团队中共同使用，以便开发人员能够有效地协同工作。你不能让左边的一个人使用复杂的数学算法，团队中的其他任何人都无法理解，并且在正确的领域中有另一种方法，他们几乎无法理解接口的实现。因此，根据经验，它们应该旨在帮助您的团队保持在一起，同时不会削弱生产力和创造力。

从整个开发团队获得一些意见，以便“房屋”标准可以包含它应该包含的所有内容，而不包括一堆不应该的内容。

Answer 5

编码指南可让其他人轻松阅读您的代码。即使您为自己编写代码并且是唯一的开发人员，找到业界普遍接受的一套指南并坚持使用它们可能会很有用。它将使您更容易阅读其他人的代码，并让您在以后适应更大的团队。

如果使用.net，请查看StyleCop。默认情况下，它包含MS自己使用的标准，并用于设计.net框架。你可以从这里得到它：

http://code.msdn.microsoft.com/sourceanalysis

您可以停用不喜欢的规则并添加自己的规则。在签入代码时，它甚至可以编写脚本来强制执行规则。最重要的是，如果你真的对这类东西不熟悉，它会告诉你你做错了什么。如果你想更进一步，看看Resharper。这是同样的事情，但在你输入的时候是实时的（虽然默认它使用的标准略有不同。

如果c＃不是您的话，我相信其他语言也有类似的实用程序！

Answer 6

我想要一个编码标准文件来解决团队的宗教争论。

对于有多个有价值答案的问题，以及人们长期争论它们的倾向，我们希望在整个项目中保持一致性，避免花费太多时间讨论它们。

很好的例子是“TABs vs. Spaces”和“K＆amp; R vs. ANSI大括号放置”。在团队中进行民意调查，做出决定并将其写下来。立即将决定应用于所有现有代码，并自行检查。永远不要再讨论了。

Answer 7

一般来说，我希望指南能够回答您通常会问的问题，但需要花费很长时间才能回答，如果您只是单独编码，这可能是“个人偏好”。通常它们会指定简洁的东西，如数据库命名约定和空格与制表符（以及多少空格）以及注释/文档注释样式。

UI指南与我认为的其他野兽不同。

我最喜欢的编码风格指南的一个例子是Linux kernel coding style，虽然它没有涉及我在其他指南中看到的细节。

Answer 8

Juval Lowy's C# coding guidelines是正确指南的一个很好的例子。我有几件事我会改变它，但在大多数情况下它太棒了。

Answer 9

我也喜欢编码风格的想法，帮助开发人员直观地识别错误/错误的代码。例如，如果某人不小心为某个浮点值或类似的东西分配了一个int，那么在其名称中包含变量的类型可以帮助我们顺利完成。

Answer 10

Code Complete是一本关于通用编程最佳实践和指南的优秀书籍，可以应用于任何语言。

它涵盖了编程的所有方面，对于想要为遇到的每个问题采用“最佳”方式做事的实际程序员来说，这是必读的。

Answer 11

编码指南是团队成员的行为规则，因此您可以毫不费力地阅读每个代码。

它还会在您的代码审核会议中获得“换行或同一行”的讨论，这样可以节省大量时间; - ）

在编写代码指南时，请确保它们出于某种原因存在，并且它们实际上可以帮助您的团队编写更易读的代码。

编码指南应该做什么，是否有任何良好的指导范例？

11 个答案: