Jump to content
  • Advertisement
Sign in to follow this  
jtrask

Commenting code - completely useless?

This topic is 4235 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

I'd like to think not... but I've been learning a lot about agile dev lately, and Refactoring mentions that comments are a good indicator that a refactoring would be useful, even if it's just to extract a single line of code into a function with a clearer name. This makes sense, and all is well and good from here. Furthermore the source code of an entire project (or subsystem or once in a while even class) might not always be self-explanatory, but for something like that I would think you'd want to collect it in some other documentation (whether external or interwoven a la Literate Programming, something a bit bigger than //). I haven't yet started applying refactoring in my own code, so I've got the theory but not the practice -- can anyone offer an example or two of when comments are warranted vs. the alternatives? Thanks

Share this post


Link to post
Share on other sites
Advertisement
It is an interesting point as a perfect bit of code would be written in such a way that it reads like English and hence needs no comments e.g. instead of writing:

// Fire the bullet
DoStuff()

you write

FireTheBullet()

it now needs no comment. Of course a very obvious example but it bears up in most cases. Whenever you write a comment in a function you are explaining something or maybe reminding yourself to do something. In the first case better naming of functions and variables will often do away with the need for a comment and in the second a proper to do tracking system is preferred.

I put comments above functions (using Doxygen notation) that can then help create automatic documentation but I avoid all comfents in functions as, like you say, they tend to indicate something that could be refactored.

A lot comes down to naming things correctly. Call your functions exactly what they do and do not worry about long names - nowadays with all the intellisense features in IDEs you rarely have to type out a whole name anyway. e.g. instead of

CalcTraj()

write

CalculateTrajectory()

Proper naming also allows you to spot refactorings, e.g. if you find you are putting an 'and' in the name it usually means you need two functions eg.

FireBulletAndCheckForCollision()

Should be split into two functions (refactors) and then called like:

FireBullet();
CheckForCollision();

The same goes for variable names. Always name a variable exactly what it is! If you are unsure then you are not clear on your own design and need to sort that out first. This also prevents the horrendous activity of reusing variables e.g. temp

Another use of comments may be to say 'only ever call this function with a valid pointer'. Again rather than put the comment up enforce it. e.g. in this case I would put in an assert:

assert(pointer!=0);

You need to be clear what you want to code, clear on the restrictions of each function and the one taks the function does and then name the function correctly, enforce the restrictions via error tests and verbosely name your variables etc.

Anyway an interesting topic... :)

Share this post


Link to post
Share on other sites
Guest Anonymous Poster
Well, I think that if some capability has been included in a language, then its for a good reason.

I believe that commenting every single line of code is, by and large, 'useless'. If you need to do that in order to understand your code, then its a good indication that it should be broken up into smaller, more manageable pieces.

However, a single comment for a block of code, a function or a module, is completely warranted. You can only gain so much by simply reading the name of a function or module. The comments should give an extra level of detail concerning the code's function and its use. Rather than trying to interpret several dozen (or more) lines of a code, reading a simple, clear and concise comment can save you loads of time when working on a larger project.

If the documentation is external, than I've got to always have that documentation open, switch to it when I need the information, and then search for the appropriate location in the document. Its much easier and faster when its right there. I'm not saying external documentation isn't helpful; it can be very helpful. But the two should probably be working in conjunction to provide the programmer what they need.

Share this post


Link to post
Share on other sites
You may want to take a look at Javadoc or Doxygen. Those tools can generate documentation based on your comments.

basically you add descriptive comments above each class and method.

looking something like this:


/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);


even if the comments might seem slightly redundant it does result in pretty impressive documentation (Fully browsable html covering all classes and methods in your project).

Share this post


Link to post
Share on other sites
Simian: Doxygen can generate most of that information without special comments. I can build references of where your function is called as well.

Share this post


Link to post
Share on other sites
  • // StartPage should be called before DrawPage
    assert ($skeleton_status === SKELETON_ACTIVE);


    My failed assertion handler in PHP automatically displays the line of code with the error, as well as the preceding comment (and a backtrace), making error messages simpler to understand than only file-line information.
  • // TODO: replace with actual function once it's done
    MockDisplay();


    During development, in-code notes from programmer to programmer (and information about how to resume work) are very useful. Arguably, quite less so during maintenance.
  • (* Little optimization trick: keep the pair *)
    | (x,0) as p when x > 0 -> right(p)


    Small code-level information might not deserve moving to its own function (especially since it's usually a small modification), but it's interesting to leave behind for the less clever programmers.
  • // Foo's algorithm: after the loop, store is never null
    assert (store);
    return *store;


    Although the overall algorithm may be described in detail in paper X, properties such as the above are best repeated in a comment, so that someone who does not wish to wade through an entire page of properties still understands why the function "magically" expects the store to be non-null.

Share this post


Link to post
Share on other sites
Yeah sure ideally we'd never need comments, but ideally we'd only to write simple code like FireZeMeeesiles(). You're going to have to use comments a lot of times when there's no easier way to quickly tell what an algorithm does, or when it's not efficient to wrap a piece of code into a easy-to-read-function.

I only use comments though because it makes my code more colorful, green and friendly. Makes it feel alive.

Share this post


Link to post
Share on other sites
I like to think that the majority of my code is easily understandable, so I use comments quite sparingly. I do however think they are extremely useful for separating out blocks of code, just so at a glance I can tell which block does what if I'm scrolling through a page. I prefer that to having a large chunk of code in a single code block, or just separating with whitespace.

Share this post


Link to post
Share on other sites
Ideals and reality rarely see eye-to-eye.

Architectures with complex template schemes, hierarchies, and special cases usually benenfit from a little comment blurb explaining how and why they work the way they do.

Even for a well-named and coded function, comments can help to clarify what is going on, especially for mathmatical or physics algorithms that other coders may not be familiar with.

Comments are usually a good idea when answers to the questions "why" or "how" about a particular piece of code are not immediately obvious.

Think about something like bump mapping and all the steps involved with it. It might make perfect sense to you, and the technique might even be well known to someone else, but how you implement it in actual code might be confusing to someone that didn't write it. It might even be confusing to you if you come back to it 4 or 5 months later.

Share this post


Link to post
Share on other sites
The one thing that I think that should be commented but almost never is; the legal values for all paramters. Can you have a null for that? are negative numbers ok? Will an empty string break things.

Doing this helps the testers and also helps people that use your functions.

theTroll

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!