How to write comments

Question

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

Answer 1

Do not comment what is obvious as

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

or

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

It might be a good idea to explain why a particular line of code exists. For example, explain why

 panel1.Invalidate(); 

Must be invalidated.

The main idea: add additional information with comments and use them for explanation, do not create redundancy and duplication.

EDIT:

You can also explain why each item in the toolbar needs to be disabled here:

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

because it’s not obvious from the name of the event handler the button is pressed to understand why all the buttons are not checked.

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 intention, not function.

It is generally useless to comment on assignments using "assign x to y" or similar.

It is much better to comment on code with a higher level of understanding of what the code seeks to ultimately achieve with pre-conditions and post-conditions. You need to comment (say) about specific implementations or checks that are necessary, but contradict the intuitive and, possibly, reference documents of the specification, etc.

If you need to comment on 50 pages of code, I suspect that you are doing this at the wrong stage of your project. I tend to comment on the intent of the class or method with the pre / post conditions before writing it. This is a mini specification form.

Answer 3

I recommend that you use XML comments in visual studio. With this, you can also automatically generate documentation for your code, as well as other developers can see which method does what using intellisense.

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

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

Answer 4

You should not waste time creating documentation now , you should refactor this code. The design is wrong in terms of class structure. Your code should be structured as much as possible so that the class has one responsibility that it is trying to achieve and have an appropriate name.

Your form 1 (bad name, btw) does too much. He must ask for other objects to help him. You might want to enter a tool class that knows which text and label cursor are appropriate. You might want to use inheritance for different shapes to make a drawing in the form. Thus, your Form1 should only delegate the current tool.

With a better structure, you can reduce the amount of documentation you have to write. You might want to find CRC cards.

Answer 5

I actually just wrote a blog post on this subject . Keep in mind that it is 100% possible (but perhaps not preferred) so that the code does not contain comments and is completely readable.