编码规范应该做什么？有没有好的规范示例？

Question

编码规范应该做什么？有没有好的规范示例？

language-agnosticuser-interfacecoding-style

8

有哪些编码准则的好例子？我并不是在寻找特定于一种语言的内容。

但是，当我撰写编码准则时应该做些什么或评估些什么呢？例如，准则应该多灵活以及应该将多少决策留给程序员或其他人或甚至由准则预先决定。

我正在制定的这套准则应涵盖广泛的主题：注释、数据库设计，甚至包括一些用户界面规范。

- jtyost2

这是一个非常广泛的问题。你最好将其拆分为几个问题，针对你感兴趣的每个主题进行提问（例如注释、数据库设计等）。 - Alex B

11个回答

9

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

- John MacIntyre

1

你遵循了什么编码准则来编写代码呢？为什么你的 reason 变量没有类型或前缀呢？ - BenAlabaster

2

我开始翻译了，但后来意识到我对这个答案过于认真了。 - John MacIntyre

8

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

每个指南应该比其带来的收益更省成本。

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

实施成本可能包括排除完全可行的替代方案、扼杀创造力和创新以及鼓励代码审查沦为强调风格上的小错误而非解决真正问题。

收益的价值可能是无形的（因此令人沮丧），对于匆忙的开发者来说可能很烦人，但可能会使你的组织品牌更加强大或更快地将新员工引入项目 - 这可能会抵消遵守规则的小幅增量成本。

- Oddthinking

我同意，我绝对不想扼杀创造力或让代码审查变成风格争论。我想要帮助确保代码可维护并且是“好”的代码（好的定义因语言而异）。 - Justin Yost

4

作为一名开发者，我通常更倾向于指南给出基本指导，但不要太严格以至于我不能按照自己的专业判断编码...例如，如果一个指南告诉我必须使用什么编码模式而不是允许我自行决定，则它太过严格：

例如，这些可能是我所期望看到的内容：

- 变量名称的样式，例如匈牙利命名法（虽然我并不严格使用这些规则） - 方法应该注释其一般用途，包括返回值（如果有的话） - 类应该以特定的布局定义：即所有私有字段在顶部，然后是事件、公共方法、私有方法，以及它们是否应按字母顺序排列 - 命名空间、类、方法、事件和属性等的命名约定

你明白了。我不应该被限制在像这样的事情上：

- “你必须使用if符号而不是int a = (blah)? true : false;”

编码风格显然需要在团队中普遍存在，以便开发人员能够有效地协作。你不能让一个人使用其他团队成员无法理解的复杂数学算法，而另一个人则难以理解接口的实现方式。因此，作为一个经验法则，它们应该被设计为帮助保持团队凝聚力，同时不会抑制生产力和创造力。

从整个开发团队获得一些意见，以便“公司”标准可以包括应该包括的所有内容，而不要包括一堆不应该包括的东西。

- balabaster

2

编码指南旨在使他人更容易阅读您的代码。即使您为自己编写代码并且是唯一的开发人员，找到行业通常接受的一套准则并坚持遵守可能会很有用。这将使您更容易阅读其他人的代码，并使您在以后加入更大的团队时适应。

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

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

您可以禁用您不喜欢的规则并添加自己的规则。它甚至可以被脚本化以在代码检查时强制执行规则。它的好处是，如果您对这种东西真的很新，它会告诉您您做错了什么。如果您想再进一步，请看一下Resharper。它是同样的东西，但是在您输入时实时进行（虽然默认情况下它使用稍微不同的标准）。我相信如果C#不是您的菜，其他语言也有类似的工具！

- DaEagle

不使用.NET，PHP/CSS/XHTML/SQL/JS但有好的建议。 - Justin Yost

1

我一直想知道为什么更多的语言定义不包括从抽象语法到具体语法的规范转换。加上一个使用这些规则和解析器来规范化具体语法的工具，将会在开始时就减少很多这种“空格放在哪里”的争议。 - Doug McClean

@Doug，如果你在1992年问我，我会指出已经存在的工具几乎可以做到这一点，并预测到世纪之交每个人都会使用像你描述的工具。我选错了！ - Oddthinking

2

我希望有一份编码规范文档来解决团队中的宗教争论。

对于存在多种可行答案且人们倾向于长时间争论的问题，我们希望在整个项目中保持一致，并避免花费过多时间讨论。

好的例子包括“TAB与空格”和“K&R与ANSI大括号放置”。在团队中进行投票，做出决定并将其记录下来。立即将该决定应用于所有现有代码, 并单独检查它。以后不要再讨论此问题。

- Jay Bazuzi

具有讽刺意味的是，我刚刚发布了一篇帖子，声称括号放置并不重要（只需确保它们存在）。但我完全同意空格问题。 - Tom

1

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

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

我最喜欢的编码风格指南之一是Linux内核编码风格，尽管它没有涉及到我在其他指南中看到的具体细节。

- jamuraa

1

Juval Lowy的C#编码准则是一个很好的范例。虽然我会对其中的一些内容进行修改，但总体来说它非常棒。

- Terry Donaghe

1

我也喜欢编码风格的想法，它可以帮助开发人员在视觉上识别出不好的/有缺陷的代码。例如，在变量名中包含变量类型可以帮助后来者避免意外地将 int 赋值为 float 等错误。

- abramN

1

《代码大全》是一本关于通用编程最佳实践和指南的优秀书籍，适用于任何语言。

它涵盖了编程的所有方面，对于想要在遇到每个问题时以“最佳”方式解决的实用程序员来说，这是必读之作。

- Jason

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Tom · Accepted Answer

编码规范通常有三个目的：

减少错误的可能性
减少分析他人编写代码所需的时间
让某些人感到强大

显然，第三个目的浪费了其他人的时间，但你需要考虑它，特别是为了避免走上这条路。

话虽如此，我注意到一些明确的做和不做：

强制执行一致的空格使用。制表符、2个空格、4个空格都无所谓，保持一致，这样缩进级别就不会因为使用不同编辑器的人而混乱。我曾经看到由于维护程序员误解了一块代码块的嵌套级别而犯了错误。
强制执行一致的日志记录方法。如果支持人员不能快速浏览日志，因为每个人的模块都有不同的日志记录原因，每个人对信息、警告和错误的定义也不同，那么这将是一个巨大的负担。
强制执行一致的错误处理。如果A模块抛出异常，B模块返回错误代码，C模块只是记录并继续执行，那么在不让错误漏掉的情况下集成它们将是一件痛苦的事情。
尽量避免琐碎的事情，比如花括号的放置。这会让很多人争论他们自己的风格，最终，它对代码的可读性并没有太大的影响。另一方面，强制使用括号的存在可能会有所不同。
在集成不同的代码库时，不要试图改变每个人的变量命名约定以匹配黄金标准。你可能有一个前进的标准，但最重要的是保持任何已经存在的本地化标准的一致性。如果一个模块使用m_member，那么维护程序员应该使用m_member2而不是应用任何其他标准（例如member2_或m_lpcstrMember2或其他）。本地一致性至关重要。

文件系统布局很重要。保持一致性，使其他人可以轻松地跳到库源码中并立即知道头文件、Makefile、源代码等在哪里。如果你使用Java或Python，这是显而易见的，因为包系统强制执行它。如果你使用C、C++或任何其他各种脚本语言，则需要自己设计一个标准布局并坚持使用。

不要过分关注细节。变量命名约定，括号或关键字之间的空格或函数名称之间的空格……大多数并不重要，因为它们并不会降低出错的可能性。每个设置的规则都应该有明确的理由，如果发现它带来的麻烦比它值得的还多，你不应该害怕改变或删除它。

不要无端地强制添加注释块。它们最终会成为废物，大多数注释最好在代码本身中表达（例如变量或函数名称）。

最后，最重要的是要定期进行同行之间的代码审查。鼓励人们在看到“代码异味”时说出来。同时也要让人们意识到建设性的代码批评并不是针对个人的 - 源代码是团队中每个人共享的，而不仅仅属于原始作者。根据我的经验，最严重的问题是设计问题，这些问题无论如何都不能通过任何编码指南来解决。软件设计仍然是一种艺术形式（好或坏），一个人的思维池比一个人的思维更好。