Question

Closed. This question is opinion-based. It is not currently accepting answers.

更新问题,可在编辑这一职位时以事实和引言回答。

Closed 5 years ago.

Improve this question

我是一个相对较新的发展者,被指派负责记录由一位先进的C#开发商撰写的编码。我的 b子告诉我,要看看它,把它记录下来,以便更容易根据需要加以修改和更新。

我的问题是:我是否应当遵循标准类型的文件/评论结构? 我的 b子使每个人都知道如何将守则记录到某种标准之中,以便人人都能理解。

我也很奇怪的是,如果有人有很好的方法将不熟悉的守则或功能不确定因素混为一谈。任何帮助都将受到高度赞赏。

Answer 1

标准似乎为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.

Answer 2

象你这样的声音确实最终导致 short倒。

不幸的是,我认为,你对软件开发中一个更具争议性的议题感到困惑。必要时,评论可视为极为有用,在错误使用时,可视为不必要的 cr。你们必须小心谨慎,认真决定什么地方。

就评论做法而言,通常由公司或开发商负责。我想使用的一些共同规则是:

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?

象你这样,我们指的是评论逻辑(很可能是为了让你开始理解这一逻辑)和使用Xml-doc评论。

如果您以前曾使用过xml-doc评论,可查到

如果你的工作量稍微大(即,许多法典要评论),我会给你一些好消息——给视觉演播室留下一个极好的景象,可以帮助你发表xml-doc评论。 <http://submain.com/products/ghostdoc.aspx” rel=“nofollow> 多功能能够使xml-doc评论方法/课程等更为容易(但会记得会在那里插入的违约地主案文!)

各位不妨在你接受幽灵教义之前,仅检查他想要证明的那部分法律。

Answer 3

令人担心的是,原来的方案管理员竟然要双手做他最重要的工作。然而,那里有许多可怕的“良好”方案制定者,因此,这实际上就是所有这种异常现象。

然而,让你把守则记录下来也是一个非常好的训练机制——在你能够撰写文件之前,你必须阅读和理解该守则,并且了解这些系统,毫无疑问,你会从好的(坏!)中挑选出几个小小小小ti。其他方案者已经做了工作。

为了帮助迅速和一致地完成你们的文件,你不妨尝试我的视频演播室附加内容,。 AtomineerUtils Pro Documentation。这将有助于开展unt辛工作,编写和更新评论意见,确保这些意见得到充分形成和与守则一致,让你集中精力处理守则本身。

如何制定守则......

希望这一类别、方法、参数和变量名称能够描述。这应当给你一个非常好的起点。然后,你可以在某个时候采取某种方法或等级,并确定你是否认为该守则提供了你认为命名意味着什么。如果进行单位测试,则将很好地说明方案人员希望守则(或处理)能够做些什么。不管怎样,试图为守则撰写一些(更多)单位测试,因为考虑到可能会破坏守则的特殊案例,以及说明该守则为什么未能进行某些测试,将会让你很好地了解它所做的工作和如何做。然后,你可以补充你以更有用的细节撰写的基本文件(这一参数可以取消?) 哪些价值观是合法的? 如果你通过空白的str,回报价值如何? 等等

这可能是令人生畏的,但是,如果你首先开始很少的班级和方法(例如,仅填上名字的财产)的话,你就会熟悉周围的法典,并能够逐步工作到更加复杂的班级和方法。

一旦你们为这些班级撰写了基本代码文件,你就应当能够撰写外部概况文件,说明整个系统是如何运作的。那么,由于你理解它如何共同适用,你就愿意就守则基础的这一部分开展工作。

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 :-)

Answer 4

我怀疑你的 b子指的是以下的XML文件评论。

Answer 5

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撰写了一些关于阅读/记录编码的博客(见的档案。

我记得:http://www.markhneedham.com/blog/2009/07/28/reading-code-rhino-mocks/“rel=“nofollow”>。阅读法:Rhino Mocks 一段时间前,会谈讨论了如何制定守则,以帮助跟踪你所处的位置,并规划下一步工作。

希望——好uck!

友情链接