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

什么是编码指南的好例子.我并不是在寻找一种特定于单一语言的东西.

但是,当我编写编码指南时,我应该做什么/评估？例如指南的灵活性以及决策应留给程序员或其他人的程度,甚至是指南预先决定的程度.

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

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

减少错误的可能性

减少分析其他人编写的代码所需的时间

给某人一个权力之旅

显然,第三个是浪费其他人的时间,但你确实需要考虑它,特别是你不要走那条路.

话虽如此,我已经注意到了一些确定的事情,而且没有.

实施一致的空白使用.标签,2个空格,4个空格,无所谓.保持一致,因此使用不同编辑器的人不会搞砸缩进级别.我看到了错误,因为维护程序员误解了代码块的嵌套级别.

实施一致的日志记录方法.如果他们无法浏览日志,那么支持人员的时间就会大量消耗,因为每个人的模块都会出于不同的原因记录,并且每个人都有不同的信息与警告与错误的定义.

实施一致的错误处理.如果模块A抛出异常,模块B返回错误代码,模块C只是记录并继续运行,将它们集成在一起并不让错误滑过裂缝将是一件痛苦的事.

尽量避免像花括号那样的小事.这会让很多人争论他们的宠物风格,最终,它对代码的可读性没有太大的影响.在另一方面,强制执行存在支架可以有所作为.

在集成不同的代码库时,不要试图改变每个人的变量命名约定以匹配黄金标准.您可能有前进的标准,但最重要的是,已经存在的任何本地化标准都会保持一致.如果一个模块使用m_member,维护程序员应该使用m_member2而不是应用任何其它标准(如member2_或m_lpcstrMember2或其他).本地一致性是王道.

文件系统布局很重要.保持一致.让某人很容易跳进库源库并立即知道头文件,Makefile,源代码等等.如果你正在使用Java或Python,这是一个明智的选择因为包系统强制执行它.如果您正在使用C,C++或任何其他无数的脚本语言,您需要自己设计标准布局并坚持使用它.

不要为小东西出汗.变量命名约定,括号或关键字或函数名之间的空格......大多数都无关紧要,因为它不会降低错误的可能性.你设定的每条规则都应该有一个具体的理由,如果你发现它引起的更多的悲伤而不是它的价值,你不应该害怕改变或删除它.

不要在任何地方强制执行无偿评论.它们最终会成为浪费,大多数注释最好不要在代码本身中表达(例如,作为变量或函数名称).

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

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

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

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

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

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

对于忙碌的开发人员而言,收益的价值可能是无形的(因而令人沮丧),但可能会导致您的组织品牌变得更强大或者让新员工更快地投入到项目中 - 这可能会超过遵守的小增量成本.