编码准则应该做什么，并有准则的好例子吗？ [英] What should coding guidelines do, and are there any good examples of guidelines?

问题描述

什么是编码指南的一些好的例子。我不是真的寻找任何特定于一种单一的语言。

What are some good examples of coding guidelines. I'm not really looking for anything specific to a single language.

但是，我应该做什么/评价，因为我编写的编码指南？例如指南应如何灵活，以及决策应留给程序员或其他人，甚至由指南预先决定。

But what should I be doing/evaluating as I write coding guidelines? Such as how flexible should the guidelines and how much should decisions be left to the programmer or to someone else or even pre-decided by the guidelines.

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

This set of guidelines that I am working on is supposed to cover a wide range of topics: comments, database design, and even some user interface guidelines.

推荐答案

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

There are generally three purposes for coding standards:

• 减少错误的可能性


• 减少分析别人写的代码所需的时间


• 给某人动力旅行

第三个是浪费别人的时间，但你确实需要考虑，特别是你不要走这条路。

Obviously, the third is a waste of everyone else's time, but you do need to consider it, specifically so you don't go down that road.

有人说，我已经注意到了一些确定的do和没有：

Having said that, there are some definite do's and dont's that I've noticed:

• 强制一致的空格使用。制表符，2空格，4空格，无关紧要。保持一致，因此缩进水平不会被使用不同编辑器的人搞砸。我看到了错误，因为维护程序员错误地解释了一段代码的嵌套层次。


• 强制执行一致的日志记录方法。如果他们无法浏览日志，这是一个巨大的漏洞，因为每个人的模块都会记录不同的原因，每个人都有不同的信息与警告与错误的定义。


• 强制执行一致的错误处理。如果模块A抛出异常，模块B返回错误代码，而模块C只是记录并继续移动，那么在不让错误通过裂缝滑动的情况下对它们进行集成将是一种痛苦。


• 尽量避免小东西，如放置大括号。这将导致很多人争论他们的宠物风格，最后，它真的不会对代码的可读性有很大的影响。另一方面，强制使用方括号的在线状态可能会有所不同。


• 集成不同的代码库时，不要改变每个人的变量命名约定以配合黄金标准。您可能有一个前进标准，但最重要的是，已经存在的任何本地化标准保持一致。如果一个模块使用 m_member ，维护程序员应该使用 m_member2 ，而不是应用任何其他标准c $ c> member2 _ 或 m_lpcstrMember2 或其他）。本地一致性是王道。


• 文件系统布局很重要。保持一致。使人们可以轻松地跳入库源代码，并立即知道标题，Makefile，源等。如果你使用Java或Python，这是一个没有脑子，因为包系统强制它。如果你使用C，C ++或任何其他无数的脚本语言，你需要自己设计一个标准的布局并坚持下去。


• 不要出汗东东。变量命名约定，括号或关键字或函数名之间的空格...大多数都没有关系，因为它不会减少出错的可能性。您设置的每个规则都应该有一个具体的理由，如果您发现它导致更多的悲伤，而不是值得的，您不应该害怕改变或删除它。


• 不要强制执行不必要的评论块到处。他们最终会浪费，大多数评论更好地表示在代码本身（例如变量或函数名称）。

• Enforce consistent whitespace usage. Tabs, 2-spaces, 4-spaces, doesn't matter. Keep it consistent, so indent levels aren't screwed up by people using different editors. I've seen mistakes made because maintenance programmers misinterpreted the nesting level of a block of code.
• Enforce consistent logging methodology. It's a huge drain on support staff's time if they aren't able to skim over logs, because everyone's module logs for different reasons, and everyone has a different definition of Info vs. Warning vs. Error.
• Enforce consistent error handling. If module A throws exceptions, module B returns error codes, and module C simply logs and moves on, it'll be a pain to integrate them without letting an error slip through the cracks.
• Try to avoid petty things like placement of curly-braces. That's going to get a lot of people arguing over their pet style, and in the end, it really doesn't have a huge impact on the readability of code. On the other hand, enforcing the presence of brackets can make a difference.
• When integrating disparate code bases, don't be tempted to change everyone's variable naming conventions to match the golden standard. You may have a standard for moving forward, but what's most important is that any localized standards that already exist are preserved consistently. If one module uses m_member, a maintenance programmer should be using m_member2 rather than applying any other standard (such as member2_ or m_lpcstrMember2 or whatever). Local consistency is king.
• Filesystem layout is important. Keep it consistent. Make it easy for someone to jump into a library sourcebase and instantly know where are the headers, the Makefile, the sources, etc. If you're working with Java or Python, this is a no-brainer because the package system enforces it. If you're working with C, C++, or any other myriad of scripting languages, you'll need to devise a standard layout yourself and stick with it.
• Don't sweat the little stuff. Variable naming conventions, spaces between parentheses or keywords or function names... most of that doesn't matter, because it doesn't reduce the likelihood of a mistake. Every rule you set should have a concrete rationale, and you shouldn't be afraid to change or remove it if you discover it's causing more grief than it's worth.
• Don't enforce gratuitous comment blocks everywhere. They'll end up as a waste, and most comments are better off being expressed in the code itself (as variable or function names, for example).

最后，最重要的是在同行之间进行常规代码审查。鼓励人们看到代码气味时大声说话。还要确保人们意识到，建设性的代码批评并不意味着是个人的 - 源是由团队共享的，它不只是属于原作者。根据我的经验，最可怕的问题是设计问题，不会被任何数量的编码指南解决。软件设计仍然是一种艺术形式（更好或更坏），一个大脑池比一个更好。

Finally, the most important thing is to have regular code reviews between peers. Encourage people to speak up when they see a "code smell." Also be sure people realize that constructive code criticism is not meant to be personal - the source is shared by everone on the team, it doesn't just belong to the original author. In my experience, the most heinous problems have been design problems that wouldn't have been solved by any amount of coding guidelines. Software design is still something of an art form (for better or for worse), and a pool of brains is much better than a single one.

这篇关于编码准则应该做什么，并有准则的好例子吗？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！