How To write comments

Question

Hi I have like 50 pages of code that I should write comments to it ... Can you guys show me the best way. I meant I need you to write me a sample ... the comments should contain nearly everything (classes, constructors, attribute, methods, events, functions)

Answer 1

Don't comment what is obvious like

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

or

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

There might be a good idea to explain WHY a certain code line is there. For example explain why

panel1.Invalidate();

Needs to be invalidated.

The basic idea is: add extra information with comments and use them for explanations, don't create redundancy and duplication.

EDIT:

You might also want to explain why each item in the toolbar needs to be unchecked here:

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

because is not obvious from the name of the event handler which button is clicked in order to understand why all buttons are unchecked.

A good comment would be something like:

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

Good comments will document intent, not function.

It's largely useless to comment assignments with "assign x to y" or similar.

It's much better to comment the code with a higher-level view of what the code aims to ultimately achieve, with pre- and post- conditions. You need to comment on (say) peculiar implementations or checks that are necessary yet counter-intuitive, and possibly reference specification documents etc.

If you've got to comment 50 pages of code, I suspect you're doing this at the wrong stage of your project. I tend to comment a class or method's intent with pre/post conditions prior to writing it. It's a form of mini-specification.

Answer 3

I recommend you to use XML comments in visual studio. Doing that you also can automatically generate documentation for your code, also other developers can see which method does what through intellisense.

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

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

Answer 4

You should not spend time writing documentation now, you should refactor this code. The design is not correct from a class-structure perspective. Your code should be structured as much as possible so that a class has a single responsibility it tries to achieve, and have a corresponding name.

Your Form1 (bad name, b.t.w.) does too much. It should ask other objects to help it. You might want to introduce a Tool class, which knows which label text and cursor are appropriate. You might want to use inheritance for the different shapes to do the drawing in a shape-specific way. In that way, your Form1 only has to delegate to the current tool.

With better structure you can reduce the amount of documentation you have to write. You might want to look up CRC-cards.

Answer 5

I actually just wrote a blog post on this subject. Bear in mind that it is 100% possible (but perhaps not preferable) for code to contain no comments and be perfectly readable.