您可以在每行文档注释的开头使用 ///。有标准的 XML 样式元素用于记录您的代码；每个都应遵循标准 Content 用法。以下是一些要素：
<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.
The standard seems to be XML Doc (MSDN Technet article here).
You can use /// at the beginning of each line of documentation comments. There are standard XML style elements for documenting your code; each should follow the standard <element>Content</element> usage. Here are some of the elements:
<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.
Sounds like you really did end up getting the short straw.
Unfortunately I think you've stumbled on one of the more controversial subjects of software development in general. Comments can be seen as extremely helpful where necessary, and unnecessary cruft when used wrongly. You'll have to be careful and decide quite carefully what goes where.
As far as commenting practice, it's usually down to the corporation or the developer. A few common rules I like to use are:
Comment logic that isn't clear (and consider a refactor)
Only Xml-Doc methods / properties that could be questioned (or, if you need to give a more detailed overview)
If your comments exceed the length of the containing method / class, you might want to think about comment verbosity, or even consider a refactor.
Try and imagine a new developer coming across this code. What questions would they ask?
It sounds like your boss is referring to commenting logic (most probably so that you can start understanding it) and using xml-doc comments.
If you haven't used xml-doc comments before, check out this link which should give you a little guidance on use and where appropriate.
If your workloadi s looking a little heavy (ie, lots of code to comment), I have some good news for you - there's an excellent plugin for Visual Studio that may help you out for xml-doc comments. GhostDoc can make xml-doc commenting methods / classes etc much easier (but remember to change the default placeholder text it inserts in there!)
Remember, you may want to check with your boss on just what parts of the code he wants documented before you go on a ghostdoc spree.
我建议使用 XML 文档（请参阅其他答案），因为 Visual Studio 会立即获取该文档并用于智能感知帮助。然后，任何编写调用您的类的代码的人都会在键入代码时在工具提示中获得帮助。当与团队或大型代码库合作时，这是一个很大的好处，但许多公司/程序员只是没有意识到他们错过了什么，在黑暗时代将他们的（未记录的）石头敲在一起:-)
It's a bit of a worry that the original programmer didn't bother to do one of the most important parts of his job. However, there are lots of terrible "good" programmers out there, so this isn't really all that unusual.
However, getting you to document the code is also a pretty good training mechanism - you have to read and understand the code before you can write down what it does, and as well as gaining knowledge of the systems, you will undoubtedly pick up a few tips and tricks from the good (and bad!) things the other programmer has done.
To help get your documentation done quickly and consistently, you might like to try my add-in for Visual Studio, AtomineerUtils Pro Documentation. This will help with the boring grunt work of creating and updating the comments, make sure the comments are fully formed and in sync with the code, and let you concentrate on the code itself.
As to working out how the code works...
Hopefully the class, method, parameter and variable names will be descriptive. This should give you a pretty good starting point. You can then take one method or class at a time and determine if you believe that the code within it delivers what you think the naming implies. If there are unit tests then these will give a good indication of what the programmer expected the code to do (or handle). Regardless, try to write some (more) unit tests for the code, because thinking of special cases that might break the code, and working out why the code fails some of your tests, will give you a good understanding of what it does and how it does it. Then you can augment the basic documentation you've written with the more useful details (can this parameter be null? what range of values is legal? What will the return value be if you pass in a blank string? etc)
This can be daunting, but if you start with the little classes and methods first (e.g. that Name property that just returns a name string) you will gain familiarity with the surrounding code and be able to gradually work your way up to the more complex classes and methods.
Once you have basic code documentation written for the classes, you should then be in a position to write external overview documentation that describes how the system as a whole functions. And then you'll be ready to work on that part of the codebase because you'll understand how it all fits together.
I'd recommend using XML documentation (see the other answers) as this is immediately picked up by Visual Studio and used for intellisense help. Then anyone writing code that calls your classes will get help in tooltips as they type the code. This is such a major bonus when working with a team or a large codebase, but many companies/programmers just don't realise what they've been missing, banging their (undocumented) rocks together in the dark ages :-)
I remember reading Reading Code: Rhino Mocks some time ago that talks about diagramming the code to help keep track of where you are and to 'map out' what's going on.
发布评论
评论（5）
标准似乎是 XML Doc （MSDN Technet 文章此处）。
您可以在每行文档注释的开头使用
///。有标准的 XML 样式元素用于记录您的代码；每个都应遵循标准Content The standard seems to be XML Doc (MSDN Technet article here).
You can use
///at the beginning of each line of documentation comments. There are standard XML style elements for documenting your code; each should follow the standard<element>Content</element>usage. Here are some of the elements:听起来你确实最终得到了短命稻草。
不幸的是，我认为您偶然发现了软件开发中最具争议性的主题之一。注释在必要时可以被视为非常有帮助，而在错误使用时则可以被视为不必要的麻烦。你必须非常小心并仔细决定什么放在哪里。
就评论实践而言，通常取决于公司或开发商。我喜欢使用的一些常见规则是：
听起来您的老板正在参考注释逻辑（很可能是为了让您可以开始理解它）并使用 xml-doc 注释。
如果您以前没有使用过 xml-doc 注释，请查看 此链接，它应该在适当的情况下为您提供一些使用指导。
如果您的工作量看起来有点繁重（即需要注释大量代码），我有一些好消息要告诉您 - Visual Studio 有一个出色的插件可以帮助您进行 xml-doc 注释。 GhostDoc 可以使 xml-doc 注释方法/类等变得更容易（但请记住更改其中插入的默认占位符文本！）
请记住，在进行 Ghostdoc 狂欢之前，您可能需要与老板核实他想要记录代码的哪些部分。
Sounds like you really did end up getting the short straw.
Unfortunately I think you've stumbled on one of the more controversial subjects of software development in general. Comments can be seen as extremely helpful where necessary, and unnecessary cruft when used wrongly. You'll have to be careful and decide quite carefully what goes where.
As far as commenting practice, it's usually down to the corporation or the developer. A few common rules I like to use are:
It sounds like your boss is referring to commenting logic (most probably so that you can start understanding it) and using xml-doc comments.
If you haven't used xml-doc comments before, check out this link which should give you a little guidance on use and where appropriate.
If your workloadi s looking a little heavy (ie, lots of code to comment), I have some good news for you - there's an excellent plugin for Visual Studio that may help you out for xml-doc comments. GhostDoc can make xml-doc commenting methods / classes etc much easier (but remember to change the default placeholder text it inserts in there!)
Remember, you may want to check with your boss on just what parts of the code he wants documented before you go on a ghostdoc spree.
令人有点担心的是，原来的程序员没有费心去做他工作中最重要的部分之一。然而，有很多糟糕的“好”程序员，所以这并不是什么不寻常的事情。
然而，让你记录代码也是一个很好的培训机制——你必须阅读并理解代码，然后才能写下它的作用，并且除了获得系统知识之外，你无疑会学到一些来自其他程序员所做的好事（和坏事！）的提示和技巧。
为了帮助您快速、一致地完成文档，您可能想尝试一下我的 Visual Studio 加载项，AtomineerUtils Pro 文档。这将有助于完成创建和更新注释的无聊繁琐工作，确保注释完全形成并与代码同步，并让您专注于代码本身。
至于弄清楚代码是如何工作的……
希望类、方法、参数和变量名称具有描述性。这应该给你一个很好的起点。然后，您可以一次采用一个方法或类，并确定您是否相信其中的代码提供了您认为命名所暗示的内容。如果有单元测试，那么它们将很好地表明程序员期望代码做什么（或处理）。无论如何，尝试为代码编写一些（更多）单元测试，因为考虑可能会破坏代码的特殊情况，并找出代码在某些测试中失败的原因，将使您更好地理解它的作用和作用它做到了。然后，您可以使用更有用的详细信息来扩充您编写的基本文档（此参数可以为空吗？什么范围的值是合法的？如果您传入空字符串，返回值是什么？等等）
这可能会令人望而生畏，但是如果您首先从小类和方法开始（例如，仅返回名称字符串的 Name 属性），您将熟悉周围的代码，并能够逐渐学习更复杂的类和方法。
一旦为类编写了基本代码文档，您就应该能够编写外部概述文档来描述系统作为一个整体如何运作。然后您将准备好处理代码库的该部分，因为您将了解它们是如何组合在一起的。
我建议使用 XML 文档（请参阅其他答案），因为 Visual Studio 会立即获取该文档并用于智能感知帮助。然后，任何编写调用您的类的代码的人都会在键入代码时在工具提示中获得帮助。当与团队或大型代码库合作时，这是一个很大的好处，但许多公司/程序员只是没有意识到他们错过了什么，在黑暗时代将他们的（未记录的）石头敲在一起:-)
It's a bit of a worry that the original programmer didn't bother to do one of the most important parts of his job. However, there are lots of terrible "good" programmers out there, so this isn't really all that unusual.
However, getting you to document the code is also a pretty good training mechanism - you have to read and understand the code before you can write down what it does, and as well as gaining knowledge of the systems, you will undoubtedly pick up a few tips and tricks from the good (and bad!) things the other programmer has done.
To help get your documentation done quickly and consistently, you might like to try my add-in for Visual Studio, AtomineerUtils Pro Documentation. This will help with the boring grunt work of creating and updating the comments, make sure the comments are fully formed and in sync with the code, and let you concentrate on the code itself.
As to working out how the code works...
Hopefully the class, method, parameter and variable names will be descriptive. This should give you a pretty good starting point. You can then take one method or class at a time and determine if you believe that the code within it delivers what you think the naming implies. If there are unit tests then these will give a good indication of what the programmer expected the code to do (or handle). Regardless, try to write some (more) unit tests for the code, because thinking of special cases that might break the code, and working out why the code fails some of your tests, will give you a good understanding of what it does and how it does it. Then you can augment the basic documentation you've written with the more useful details (can this parameter be null? what range of values is legal? What will the return value be if you pass in a blank string? etc)
This can be daunting, but if you start with the little classes and methods first (e.g. that Name property that just returns a name string) you will gain familiarity with the surrounding code and be able to gradually work your way up to the more complex classes and methods.
Once you have basic code documentation written for the classes, you should then be in a position to write external overview documentation that describes how the system as a whole functions. And then you'll be ready to work on that part of the codebase because you'll understand how it all fits together.
I'd recommend using XML documentation (see the other answers) as this is immediately picked up by Visual Studio and used for intellisense help. Then anyone writing code that calls your classes will get help in tooltips as they type the code. This is such a major bonus when working with a team or a large codebase, but many companies/programmers just don't realise what they've been missing, banging their (undocumented) rocks together in the dark ages :-)
我怀疑你的老板指的是以下 XML 文档注释。
XML 文档注释（C# 编程指南）
I suspect your boss is referring to the following XML Documentation Comments.
XML Documentation Comments (C# Programming Guide)
可能值得询问您的老板是否有任何已记录的代码示例，以便您可以直接了解他所追求的内容。
Mark Needham 写了一些关于阅读/记录代码的博客文章（请参阅 “阅读”的存档 。
我记得读过阅读代码：Rhino Mocks 不久前讨论了用图表绘制代码以帮助跟踪您所在的位置并“绘制”正在发生的事情
希望有所帮助 - 祝您好运！
It might be worth asking your boss if he has any examples of code that is already documented so you can see first-hand what he is after.
Mark Needham has written a few blog posts about reading/documenting code (see Archive for the ‘Reading Code’ Category.
I remember reading Reading Code: Rhino Mocks some time ago that talks about diagramming the code to help keep track of where you are and to 'map out' what's going on.
Hope that helps - good luck!