Click here to Skip to main content
15,077,494 members
Please Sign up or sign in to vote.
3.00/5 (1 vote)
See more:
Ive been searching for some time, and while im not exactly new to programming, commenting standards has always been something i have never really grasped properly. I know everyone will have a difference concept, but in general my question is:

Say i have a button, and wish to comment the click method in the code behind.
C#
/// ************************************************************************
///
/// ************************************************************************
protected void randomButton_Click(object sender, EventArgs e)
{
    // Does something
}



In the comment section, am i meant to be commenting what the method actually does, or that infact it is a button click event?

eg. // Method that fires on randomButton click
or
// This method does some random functionality blah blah.

Any advice would be appreciated, thanks in advance.
Posted
Updated 16-Oct-13 18:12pm
v2

No, this cannot be an event. Event is something very different. Maybe, you need to read about events. At best, this method could be used as an event handler, but so many beginners have been confused by the fact that, by some reason, it is not. Besides, it could be much better to use anonymous method; and you could call some more semantically-named method from this anonymous method, without all of your arguments like sender and e, as one or both of them are often not used in method implementation.

So, the point is: before commenting a method and explaining what it does, name the method properly, maybe, it would highly reduce the need for a comment. And — previous step — before renaming a method, you need to write better code.

Going back to naming, your method name brutally violates (good, I think) Microsoft naming conventions: using '_' is a very bad style. But more importantly, if should not be named after the button name: its name should reflect what it does. This is how your need for comment can be reduced, but reading comments is not a main part of readability. Good code is self-commenting.

By the way, leaving as is all those auto-generated names is extremely bad idea. Why do you think you are given a refactorization engine? You need to rename all auto-generated names as soon as you start using them. Such auto-generated names violate all thinkable naming and readability principles by definition: the engine does no "know" your semantic, only you do.

So, your example is not ready for commenting, and, probably, you are not ready, too. Before you develop strong opinion on how to comment, it's much better not to comment at all. I'm not joking. Most developers actually over-comment code. You may say that it's important to comment something important. If you say so, you will be absolutely right. The thing is: people who don't comment that really important things and people who over-comment are… the same people.

How to learn commenting? Not an easy question. I would not promise to cover it even in a big article: it takes learning how to write good clean code, and analyze many different examples. Few simple rules and "standards" won't help. Just one advice: read your own code. At least your own. Wait until the code is fully developed, debugged, tested and a bit forgotten, and then read again. Better yest, read it after you did not look at it for an year or so. You are supposed to understand your code very well. But chances are, it will be difficult. Try to analyze why. This would be the best lesson of commenting.

Good luck,
—SA
   
Comments
[no name] 17-Oct-13 1:08am
   
I agree with this. A comment is needed when the code is not self explanatory.
   
Thank you very much.
More exactly, not all code can possibly self-explanatory, and this is where comments are needed the most. There are other cases... copyright, URLs, contact information... documentation bases on XML comments... and so on...
—SA
According to Microsoft standards, create summary for all the methods.
If you want to follow comment and coding standards you may use StyleCop.

See below example of button click event.

XML
/// <summary>
/// Method button click event. Get data for the selected method
/// </summary>
/// <param name="sender">
/// object sender.
/// </param>
/// <param name="e">
/// Event arguments
/// </param>
protected void buttonMethod_Click(object sender, EventArgs e)
{
}
   
Comments
   
Well, you followed the rules and... the code is the pain to look at. Do you understand yourself how bad it is?
—SA
CodeBlack 17-Oct-13 0:36am
   
I don't feel it bad. as it helps for the documentation as well and also if some new member has joined the development team then he/she can get an basic idea about what this method is doing actually.
   
I understand. And this is a problem. I think I explained in my answer what's wrong about it. And such comments are only need for XML comments (shown during development), so they can be only on members and types visible from a different assemblies (protected, public). And this method should not be protected. It should not even exist, frankly.
—SA

This content, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)




CodeProject, 20 Bay Street, 11th Floor Toronto, Ontario, Canada M5J 2N8 +1 (416) 849-8900