Question

您好，我有50页的代码，我应该给它写评论...... 你们能告诉我最好的方法吗？我的意思是我需要你给我写一个样本...... 注释应该包含几乎所有内容（类，构造函数，属性，方法，事件，函数）

Answer 1

不要评论显而易见的内容

//The width of the line is 2
lineWidth = 2;

或

//Clones the snapshot
tempDraw = (Bitmap)snapshot.Clone();

可能有一个好主意可以解释为什么某个代码行存在。例如解释原因

panel1.Invalidate();

需要失效。

基本思想是：添加带注释的额外信息并将其用于解释，不要创建冗余和重复。

编辑：

您可能还想解释为什么需要在此处取消选中工具栏中的每个项目：

private void toolStripButton1_Click(object sender, EventArgs e)
{
    foreach (ToolStripButton btn in toolStrip1.Items)
    {
        btn.Checked = false;
    }
...
}

因为从事件处理程序的名称中看不明显哪个按钮被单击以便理解为什么所有按钮都未被选中。

好评如下：

private void toolStripButton1_Click(object sender, EventArgs e)
{
    //Deselect all previously applied filters because the user clicked "disable all",
    //which removes the effects of all filters and we want to show this the the user
    foreach (ToolStripButton btn in toolStrip1.Items)
    {
        btn.Checked = false;
    }
...
}

Answer 2

好的评论会记录意图，而非功能。

用“分配x到y”或类似的方式来评论作业是没用的。

使用更高级别的代码来评论代码，以及在条件前和后期条件下最终实现的目标，这样做要好得多。您需要评论（比如）必要但反直觉的特殊实现或检查，并可能参考规范文档等。

如果您要评论50页代码，我怀疑您是在项目的错误阶段进行此操作。我倾向于用前/后条件之前来评论一个类或方法的意图来编写它。这是一种迷你规范。

Answer 3

我建议您在visual studio中使用XML注释。这样做也可以自动为代码生成文档，其他开发人员也可以通过intellisense查看哪种方法可以做什么。

http://www.winnershtriangle.com/w/Articles.XMLCommentsInCSharp.asp

http://msdn.microsoft.com/en-us/magazine/cc302121.aspx

Answer 4

你应该不花时间编写文档现在，你应该重构这段代码。从类结构的角度来看，设计是不正确的。您的代码应该尽可能地构建，以便类具有它试图实现的单一职责，并具有相应的名称。

你的Form1（坏名字，b.t.w。）做得太多了。它应该要求其他对象来帮助它。您可能想要引入一个Tool类，它知道哪个标签文本和光标是合适的。您可能希望使用不同形状的继承来以特定于形状的方式进行绘制。这样，Form1只需委托当前工具。

通过更好的结构，您可以减少必须编写的文档数量。您可能想要查找CRC卡。

Answer 5

我其实只是写了blog post on this subject。请记住，对于不包含注释且完全可读的代码，100％可能（但可能不是更可取）。

如何写评论

5 个答案: