如何写评论

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页代码,我怀疑您是在项目的错误阶段进行此操作.在编写之前,我倾向于用前/后条件评论一个类或方法的意图.这是一种迷你规格.