编写c#代码的规则/指导方针

本文关键字：指导方针 规则 代码 编写 | 更新日期: 2023-09-27 18:09:27

我是一名相对较新的开发人员，并被分配了一项由高级c#开发人员编写的代码文档的任务。我的老板让我把它通读一遍，并把它记录下来，以便在需要时更容易修改和更新。

我的问题是:是否有我应该遵循的标准类型的文档/注释结构?我的老板说得好像每个人都确切地知道如何按照某种标准编写代码，以便任何人都能理解它。

我也很好奇是否有人有一个很好的方法来找出不熟悉的代码或函数的不确定性。任何帮助都将非常感激。

编写c#代码的规则/指导方针

标准似乎是XML Doc (MSDN Technet文章在这里)。

您可以在文档注释的每行开头使用///。有标准的XML样式元素用于记录代码;每个都应该遵循标准的<element>Content</element>用法。以下是一些元素:

<c>               Used to differentiate code font from normal text 
                    <c>class Foo</c>
<code>
<example>
<exception>
<para>            Used to control formatting of documentation output. 
                    <para>The <c>Foo</c> class...</para>
<param>
<paramref>        Used to refer to a previously described <param>  
                    If <paramref name="myFoo" /> is <c>null</c> the method will...
<remarks>
<returns>
<see>             Creates a cross-ref to another topic. 
                     The <see cref="System.String" /><paramref name="someString"/>
                     represents...
<summary>         A description (summary) of the code you're documenting.

听起来你真的是被人亏了。

不幸的是，我认为您无意中发现了软件开发中一个更有争议的主题。注释在必要的时候是非常有用的，而在使用不当的时候则是不必要的废话。你必须非常小心，非常仔细地决定把什么放在哪里。

就评论实践而言，这通常取决于公司或开发人员。我喜欢使用的一些常见规则是:

  • 注释逻辑不清晰(考虑重构)
  • 只有可以被质疑的Xml-Doc方法/属性(或者，如果你需要给出更详细的概述)
  • 如果你的注释超过了包含方法/类的长度，你可能需要考虑注释的冗长性，甚至考虑重构。
  • 试着想象一个新的开发人员遇到这段代码。他们会问什么问题?

听起来你的老板指的是注释逻辑(很可能是为了让你开始理解它)，并使用xml-doc注释。

如果你以前没有使用过xml-doc注释，请查看这个链接，它应该会给你一些使用和适当的指导。

如果你的工作量看起来有点重(例如，有很多代码要注释)，我有一些好消息要告诉你——Visual Studio有一个很好的插件，可以帮助你解决xml-doc注释问题。GhostDoc可以使xml-doc注释方法/类等更容易(但请记住更改它插入的默认占位符文本!)

请记住，在你疯狂地写ghostdoc之前，你可能想和你的老板确认一下他想要记录代码的哪些部分。

原来的程序员没有费心去做他工作中最重要的部分之一，这有点令人担心。然而，有很多糟糕的"好"程序员，所以这并不是那么不寻常。

然而，让你记录代码也是一个很好的训练机制——在你写下代码的功能之前，你必须阅读和理解代码，以及获得系统的知识，毫无疑问，你将从其他程序员所做的好事(和坏事!)中获得一些技巧和技巧。

为了帮助您快速一致地完成文档，您可能想尝试我的Visual Studio插件，AtomineerUtils Pro documentation。这将有助于完成创建和更新注释的单调乏味的工作，确保注释完全形成并与代码同步，并让您专注于代码本身。

至于代码是如何工作的…

希望类、方法、参数和变量的名称是描述性的。这应该给你一个很好的起点。然后，您可以一次选择一个方法或类，并确定您是否相信其中的代码交付了您认为命名所暗示的内容。如果有单元测试，那么这些将很好地指示程序员期望代码做什么(或处理什么)。无论如何，尝试为代码编写一些(更多)单元测试，因为考虑可能破坏代码的特殊情况，并找出代码无法通过某些测试的原因，将使您很好地理解它是做什么的以及它是如何做的。然后，您可以用更有用的细节(这个参数可以为空吗?什么范围的值是合法的?如果传入一个空字符串，返回值是什么?等)

这可能会让人望而生畏，但如果你先从小的类和方法开始(例如，Name属性只返回一个名称字符串)，你将熟悉周围的代码，并能够逐步工作到更复杂的类和方法。

一旦你为类编写了基本的代码文档，你就应该能够编写外部概述文档来描述系统作为一个整体是如何工作的。然后你将准备好处理那部分代码库，因为你将了解它们是如何组合在一起的。

我建议使用XML文档(参见其他答案)，因为它可以立即被Visual Studio接收并用于智能感知帮助。然后，任何编写调用您的类的代码的人在键入代码时都将在工具提示中获得帮助。当与一个团队或大型代码库一起工作时，这是一个很大的好处，但许多公司/程序员只是没有意识到他们错过了什么，在黑暗时代敲打他们的(未记录的)岩石:-)

我怀疑你的老板指的是以下XML文档注释。

XML文档注释(c#编程指南)

如果你的老板有任何已经记录的代码示例，那么你可以直接看到他在寻找什么。

Mark Needham已经写了一些关于阅读/记录代码的博文(参见Archive的"阅读代码"类别)。

我记得前一段时间读过《阅读代码:Rhino模拟》，它讨论了如何用图表化代码来帮助跟踪你在哪里，并"绘制"出正在发生的事情。

希望有帮助-祝你好运!

相关文章：