commenting code properly

Question

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 16-Oct-13 17:44pm

nebiam

Updated 16-Oct-13 18:12pm

Captain Price

v2

Add a Solution

2 solutions

Add a Solution

Add your solution here

Treat my content as plain text, not as HTML

Preview 0

…

Existing Members

Sign in to your account

...or Join us

Download, Vote, Comment, Publish.

Your Email
Password
Forgot your password?

Your Email
This email is in use. Do you need your password?
Optional Password

I have read and agree to the Terms of Service and Privacy Policy
Please subscribe me to the CodeProject newsletters

When answering a question please:

Read the question carefully.
Understand that English isn't everyone's first language so be lenient of bad spelling and grammar.
If a question is poorly phrased then either ask for clarification, ignore it, or edit the question and fix the problem. Insults are not welcome.
Don't tell someone to read the manual. Chances are they have and don't get it. Provide an answer or move on to the next question.

Let's work to help developers, not make them feel stupid.

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

Sergey Alexandrovich Kryukov · Accepted Answer · 2013-10-16T18:31:00

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

CodeBlack · Accepted Answer · 2013-10-16T18:17:00

Solution 1

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)
{
}

Posted 16-Oct-13 18:17pm

CodeBlack

Comments

Sergey Alexandrovich Kryukov 17-Oct-13 0:32am

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.

Sergey Alexandrovich Kryukov 17-Oct-13 0:47am

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