对开发 C# 编码标准/最佳实践文档有什么建议吗？

Are there any suggestions for developing a C# coding standards / best practices document?

提问by TK.

I'm a recent AI graduate (circa 2 years) working for a modest operation. It has fallen to me (primarily as I'm the first 'adopter' in the department) to create a basic (read useful?) C# coding standards document.

我是一名最近的 AI 毕业生（大约 2 年），为一家规模不大的公司工作。创建基本（阅读有用？）C# 编码标准文档的责任落在了我身上（主要是因为我是该部门的第一个“采用者”）。

I think I should explain that I'm probably the most junior software engineer going, but I'm looking forward to this task as hopefully I might actually be able to produce something half usable. I've done a pretty extensive search of the Internet and read articles on what a coding standards document should / should not contain. This seems like a good as place as any to ask for some suggestions.

我想我应该解释一下，我可能是最初级的软件工程师，但我很期待这项任务，因为希望我实际上能够生产出一半可用的东西。我已经在 Internet 上进行了相当广泛的搜索，并阅读了有关编码标准文档应该/不应该包含哪些内容的文章。这似乎是一个寻求一些建议的好地方。

I realise that I am potentially opening a door to a whole world of disagreement about 'the best way to do things'. I both understand and respect the undeniable fact that each programmer has a preferred method of solving each individual task, as a result I'm not looking to write anything so draconianly proscriptive as to stifle personal flair but to try and get a general methodology and agreed standards (e.g. naming conventions) to help make individuals code more readable.

我意识到我可能会打开一扇大门，通向整个世界关于“做事的最佳方式”的分歧。我既理解又尊重一个不可否认的事实，即每个程序员都有解决每个单独任务的首选方法，因此我不想写任何严厉禁止以扼杀个人天赋的东西，而是尝试获得通用方法并同意标准（例如命名约定）以帮助使个人代码更具可读性。

So here goes .... any suggestions? Any at all?

所以这里......有什么建议吗？有吗？

采纳答案by ESV

We start with

我们从

• Microsoft's .NET guidelines: http://msdn.microsoft.com/en-us/library/ms229042.aspx(link updated for .NET 4.5)
• Microsoft's C# guidelines: http://blogs.msdn.com/brada/articles/361363.aspx.

• Microsoft 的 .NET 指南：http: //msdn.microsoft.com/en-us/library/ms229042.aspx（针对 .NET 4.5 更新了链接）
• Microsoft 的 C# 指南：http: //blogs.msdn.com/brada/articles/361363.aspx。

and then document the differences from and additions to that baseline.

然后记录与该基线的差异和添加。

回答by Keith

Microsoft's own rules are an excellent starting point. You can enforce them with FxCop.

微软自己的规则是一个很好的起点。您可以使用 FxCop 强制执行它们。

回答by Dale Ragan

I have always used Juval Lowy's pdfas a reference when doing coding standards / best practices internally. It follows very close to FxCop/Source Analysis, which is another invaluable tool to make sure that the standard is being followed. Between these tools and references, you should be able to come up with a nice standard that all your developers won't mind following and be able to enforce them.

在内部进行编码标准/最佳实践时，我一直使用 Juval Lowy 的pdf作为参考。它非常接近FxCop/ Source Analysis，这是确保遵循标准的另一个非常宝贵的工具。在这些工具和参考之间，您应该能够提出一个很好的标准，您的所有开发人员都不会介意遵循并能够执行它们。

回答by denis phillips

IDesignhas a C# coding standards document that is commonly used. Also see the Framework Design Guidelines 2nd Ed.

IDesign有一个常用的 C# 编码标准文档。另请参阅框架设计指南第 2 版。

回答by denis phillips

The other posters have pointed you at the baseline, all I would add is make your document short, sweet, and to the point, employing a heavy dose of Strunk and White to distinguish the "must haves" from the "it would be nice ifs".

其他海报已将您指向基线，我要补充的只是使您的文档简短，甜蜜，并且重点突出，使用大量的 Strunk 和 White 来区分“必须拥有”和“如果是这样就好了” ”。

The problem with coding standards documents is that nobody really reads them like they should, and when they do read them, they don't follow them. The likelihood of such a document being read and followed varies inversely with its length.

编码标准文档的问题在于，没有人真正按照他们应该的方式阅读它们，而且当他们阅读它们时，他们并没有遵循它们。此类文档被阅读和跟踪的可能性与其长度成反比。

I agree FxCop is a good tool but too much of this can take all the fun right out of programming, so be careful.

我同意 FxCop 是一个很好的工具，但是太多了会失去编程的乐趣，所以要小心。

回答by Andrew Grant

Ironically setting the actual standards are likely to be the easy part.

具有讽刺意味的是，制定实际标准可能是容易的部分。

My first suggestion would be to elicit suggestions from the other engineers about what they feel should be covered, and what guidelines they feel are important. Enforcing any kind of guidelines requires a degree of buy-in from people. If you suddenly drop a document on them that specifies how to write code you'll encounter resistance, whether you're the most junior or senior guy.

我的第一个建议是从其他工程师那里征求他们认为应该涵盖的内容以及他们认为重要的指导方针的建议。执行任何类型的准则都需要人们一定程度的认同。如果你突然在他们身上丢下一份文件，说明如何编写代码，你会遇到阻力，无论你是初级还是高级的人。

After you have a set of proposals then send them out to the team for feedback and review. Again, get people to all buy into them.

在您有了一组提案后，将它们发送给团队进行反馈和审查。再次，让人们都买进他们。

There may already be informal coding practices that are adopted (e.g prefixing member variables, camelcase function names). If this exists, and most code conforms to it, then it will pay to formalize its use. Adopting a contrary standard is going to cause more grief than it's worth, even if it's something generally recommended.

可能已经采用了非正式的编码实践（例如，为成员变量添加前缀、驼峰式函数名称）。如果存在，并且大多数代码都符合它，那么将其使用形式化是值得的。采用相反的标准会导致比其价值更多的悲伤，即使它是普遍推荐的。

It's also worth considering refactoring existing code to meet the new coding-standards. This can seem like a waste of time, but having code that does not meet the standards can be counter-productive as you will have a mish-mash of different styles. It also leaves people in a dilemma whether code in a certain module should conform to the new standard or follow the existing code style.

还值得考虑重构现有代码以满足新的编码标准。这似乎是在浪费时间，但拥有不符合标准的代码可能会适得其反，因为您将拥有不同风格的大杂烩。这也让人们陷入困境，某个模块中的代码是应该遵循新标准还是遵循现有的代码风格。

回答by Rob Cooper

I think I echo the other comments here that the MS guidlines already linked are an excellent starting point. I model my code largely on those.

我想我在这里回应了其他评论，即已经链接的 MS 指南是一个很好的起点。我的代码主要基于这些建模。

Which is interesting because my manager has told me in the past that he is not too keen on them :D

这很有趣，因为我的经理过去曾告诉我，他不太热衷于他们：D

You have a fun task ahead of you my friend. Best of luck, and please ask if you need anything more :)

你有一个有趣的任务摆在你面前，我的朋友。祝你好运，请询问您是否需要更多:)

回答by Adam V

You are most likely being set up to fail. Welcome to the industry.

你很可能被设置为失败。欢迎来到这个行业。

I disagree - so long as he creates the document, the worst that can happen is that it gets forgotten by everyone.

我不同意 - 只要他创建文档，可能发生的最坏情况就是每个人都忘记它。

If other people have issues with the content, then you can ask them to update it to show what they'd prefer. That way it's off your plate, and the others have the responsibility to justify their changes.

如果其他人对内容有疑问，那么您可以要求他们更新内容以显示他们喜欢的内容。这样就不用你说了，其他人有责任证明他们的改变是合理的。

回答by David Hayes

Never write your own coding standards use the MS ones (or the Sun ones or ... as appropriate for your language). The clue is in the word standard, the world would be a much easier place to code in if each organization hadn't decided to write their own. Who really thinks learning a new set of 'standards' each time you change teams/projects/roles is a good use of anyone's time. The most you should ever do is summarize the critical points but I'd advise against doing even that because what is critical varies from person to person. Two other points I'd like to make on coding standards

永远不要编写自己的编码标准，使用 MS 标准（或 Sun 标准或...适合您的语言）。线索就在标准这个词中，如果每个组织都没有决定编写自己的代码，那么世界将是一个更容易编码的地方。谁真的认为每次更换团队/项目/角色时学习一套新的“标准”是对任何人时间的很好利用。您最应该做的是总结关键点，但我建议您不要这样做，因为关键点因人而异。我想就编码标准提出另外两点

1. Close is good enough - Changing code to follow coding standards to the letter is a waste of time as long as the code is close enough.
2. If you're changing code you didn't write follow the 'local coding standards', i.e. make your new code look like the surrounding code.

1. 接近就足够了 - 只要代码足够接近，更改代码以遵循编码标准就是浪费时间。
2. 如果您要更改未编写的代码，请遵循“本地编码标准”，即让您的新代码看起来像周围的代码。

These two points are the reality to my wish that everybody would write code that looked the same.

这两点是我希望每个人都编写看起来相同的代码的现实。

回答by Joe

The standard from Philips Medical Systems is well written, and mostly follows Microsoft guidelines: www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

飞利浦医疗系统的标准写得很好，主要遵循微软的指导方针：www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

My standards are based on this with a few tweaks, and some updates for .NET 2.0 (the Philips standard is written for .NET 1.x so is a bit dated).

我的标准基于此并进行了一些调整，并针对 .NET 2.0 进行了一些更新（飞利浦标准是为 .NET 1.x 编写的，因此有点过时）。