创建编码标准文档

我在一家控制系统公司工作，主要工作是SCADA和PLC以及其他控制系统。

除非决定创建内部项目管理和评估系统，否则软件开发实际上不是公司要做的事情。

这个项目最初是由来这里从事软件工作的人们承担的，我们大多是初级的。

该项目起初很小，所以我们只记录设计，数据库等内容，但我们从未真正同意编码格式/惯例。

我们开始使用StyleCop来确保我们已编写了完整的代码，但是我认为我们需要一个正式的文档来编写编码约定/实践，以便我们可以继续制定一个良好的标准，并且如果将来还有其他重要的开发工作（无论谁在此工作），具有良好的底板。

问题就出在这里，我不知道如何起草编码惯例和标准的文档，我所能想到的只是良好实践与不良实践的例子（例如，在命名变量，避免匈牙利符号等情况下的驼峰案例），我们都是能干足够的程序员（显然），但是我们只是没有关于这类东西的章程。

首先，我的问题是：好的编码标准文档的关键方面和内容是什么？

好的编码标准文档的关键方面和内容是什么？

1. 正在通过实现自动化的检查代码的工具支持。如果我知道我不能致力于任何与某些规则不匹配的代码的版本控制，那么将鼓励我在代码中遵循这些规则。另一方面，如果某个程序员的同伴在某个地方写了我需要遵循的规则，那么我就不会对这些规则一无所知。

2. 作为深思熟虑的，而不是被你个人的意见。您不能简单地说：“从现在开始，我们不再使用区域，因为我不喜欢区域。” 相反，您将解释说区域会鼓励代码增长，并且不会解决任何主要问题。

   原因是在第一种情况下，您的同事会回答：“好吧，我喜欢区域，所以我仍然会使用它们”。另一方面，在第二种情况下，这将迫使不同意的人提出建设性的批评，建议和论点，最终使您改变自己的原始观点。

3. 而有据可查的。文件的缺乏造成混乱和解释的空间 ; 混淆和解释的可能性导致样式差异，即标准要抑制的事物。

4. 作为广泛，包括公司外部。与全世界成千上万的开发人员所熟知的标准相比，二十个程序员所使用的“标准”要低一些。

既然您在谈论StyleCop，我想该应用程序是用.NET Framework语言之一编写的。

在这种情况下，除非您有认真的理由采取不同的措施，否则请遵守Microsoft的准则。这样做而不是创建自己的标准有很多好处。考虑前面的四点：

1. 您无需重写StyleCop规则即可满足自己的标准。我并不是说很难编写自己的规则，但是如果您可以避免这样做，则意味着您有更多的时间来做一些有用的事情。

2. 微软的准则是经过深思熟虑的。如果您不同意其中的一些，则可能是因为您不了解它们。这正是我的情况；当我开始C＃开发时，我发现一些完全愚蠢的规则。现在，我完全同意他们的观点，因为我终于理解了为什么要这样写。

3. Microsoft的指南已被详细记录，因此您不必编写自己的文档。

4. 稍后将在您公司中雇用的新开发人员可能已经熟悉Microsof的编码标准。有可能没有人会熟悉您的内部编码风格。

首先要注意的是，编码标准文档与正确与否无关。这不是好事，也不是哪种方法更好。

编码标准文档的目的是确保所有代码的设计，编写和布局均相同，从而使开发人员可以更轻松地从一个人的工作切换到另一个人，而无需改变心态来阅读别人的风格。

一切都与统一性有关，与“对与错”无关

考虑到这一点，您应该在编码标准文档中阐明以下几点：

命名约定

您将如何命名方法，变量，类和接口？您将使用哪种表示法？

我们的标准中还包括了SQL的分离标准，因此我们对表，过程，列，id字段，触发器等有相似的名称。

缩进

您将使用什么进行缩进？一个标签？3个空格？

布局

括号是否与打开方法行保持在同一行？（通常是Java）还是下一行还是自己的一行？（通常为C＃）

异常处理/记录

您对异常处理和日志记录的标准是什么，是全部自行开发还是使用第三方工具？应该如何使用？

评论

我们有指示语法正确性的标准，并且注释在同一行之前或之后而不是同一行开始，这提高了可读性。注释是否必须缩进到与代码相同的深度？您会接受大文本周围使用的那些注释边框吗？

描述方法上的\\\怎么样？这些会被使用吗？什么时候？

曝光

您所有的方法和字段都应该实现最低级别的访问吗？

也是要注意的重要事项。好的标准文档可以在帮助审查代码方面大有帮助，是否符合这些最低标准？

我几乎没有涉及其中一份文件的内容，但是KISS

不要让它冗长，无聊，不可能通过，否则就不会遵循那些标准，请保持简单。

我多次经历了这个过程。最成功的方法（尽管还是很坎bump）是从知名公司那里获取“编码标准”文档并对其进行修改以满足您的需求。

例如，我刚刚找到了一个：http : //www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

无论如何，请保持随身携带喷火器。

干杯，

我讨厌大多数标准文档，因为它们通常会尝试耗费少量精力而忽略较大的内容。

例如，几乎所有人都会说出如何命名变量或放置方括号。这是纯粹的样式，对真正帮助一组开发人员代码没有任何帮助。他们忽略目录结构和代码布局之类的东西。我看过一些标准文档，这些文档告诉您确切的运算符之间应放置多少空格，方法之间应包含多少空白行。所有这些通常都以规则的大量例外而告终，这只是表明它们实际上是毫无意义的，然后它们是如此之大，没人能跟随它们，这再次嘲弄了他们试图提出的观点。 。

现在对我来说，我使用来自许多不同人的许多不同软件，并且它们都有不同的样式。我只是习惯了这一点，所以我不会抱怨所有开发团队之间都没有共同的风格。只要代码是整个项目中的通用样式，我真的不在乎该样式是什么。因此，我对所有标准文档的第一条规则是：在项目中保持一致的编码风格。只要括号都相同，就没人要在括号中放一个无花果。参加宗教战争并推sho他们:)

第二个是代码布局。当我拿起一段代码时，我想看看它的布局与其他类似的工作是相似的。如果我有一个Web服务，则我希望wsdl合同的名称清晰，我希望实现的名称清晰。我不希望有人想出一种全新的文件和类的不同布局。这意味着我必须玩“寻找代码”，这很麻烦。如果它看起来与我上一个工作的项目相同，那么我可以立即知道在哪里可以找到我要寻找的内容，这可能是使用我所知道的其他人代码的最大帮助。因此，请保持代码布局的结构（例如，用于文档的“文档”文件夹，用于接口的接口等-不管它对您有用还是坚持使用）。

代码工件也应该存在，因此您需要说出预期的错误处理是异常还是错误代码，即。记录正在使用的架构功能。还应说明要使用哪种日志记录以及如何向用户提供日志/错误处理或使用任何子系统来野外管理代码。我在每个项目的日志记录都不同的地方工作-每个代码版本必须有自己的不同操作文档，告诉操作人员如何判断是否出错，这真可悲。事件日志，日志文件（在这种情况下）在此处均有效。这同样适用于代码的其他常见方面-如何配置它（对于某些程序，对于自定义DB，命令行参数，对于其他程序，则无需使用.config文件。

简而言之，唯一重要的是Consistency。而且由于巨大的标准文档太多了，难以阅读和记忆，我宁愿只告诉人们他们看不到的内容（例如，诸如日志记录之类的体系结构标准），并告诉他们使编写的代码与当前代码保持一致。而且，如果您还没有代码，则不需要标准文档！（嗯，直到您编写足够有用的内容为止）。

因此，请注意以下要点：不要试图制作法律文档，不要仅仅考虑编码，还应考虑代码的工作方式以及代码如何符合其他人的期望。然后信任人们去执行良好的代码，您就会看到他们在做。（如果他们不这样做，您可以与他们谈谈，无需像法律那样将其放下）。

不，这是在浪费时间和精力。StyleCop很棒，它是由比您或团队中任何人都经验更丰富，更聪明的人们建立的。拥抱并爱上它！它可以连续地为您提供指导，这比任何等待有人打扰的文档要好。