Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I was browsing some old code that I wrote (first year in the university) and noticed that I used to write comment titles preceeding various parts of the code. Stuff like (this is from a Monopoly game):

/*Board initialization*/
...code...

/*Player initialization*/
...code...

/*Game logic starts here*/
/*Displaying current situation*/
...code...

/*Executing move*/
...code...

/*Handle special event*/
...code...

/*Commit changes, switch to next player*/
...code...

This might be redundant, and arguably unnecessary if the code is really super clear, but as I scanned through the file it surprised me how strongly I felt like I know what's going on even though I hardly looked at the actual code. I can definitely see this as being fitting in certain circumstances, so I wonder- do you do this? Do you think it's a good idea? Or is it too much?

share|improve this question
add comment

6 Answers

up vote 25 down vote accepted

This is a code smell. This says what and not why.

If this is necessary, split the code in small functions.

share|improve this answer
3  
There's no point in having functions to have functions. –  Paul Nathan Sep 15 '10 at 20:59
28  
is right: if code deserves a comment like /*Board initialization*/, it probably ought to be in a function called InitializeBoard. If your code structure is clear enough then you won't need comments. –  Tim Robinson Sep 15 '10 at 21:58
3  
The "what" is good to know, and often isn't obvious from looking at the code. These comments make the overall intent clear. –  DarenW Dec 8 '10 at 22:05
4  
@DarenW - but so do functions/procedures/methods. And the later have the added benefit of modularizing the code, which makes it easier to understand. –  Stephen C Sep 25 '11 at 8:08
3  
Another benefit of this is that functions such as InitializeBoard or InitializePlayer will appear in function/module/class browser lists of most IDEs whereas comments will not. Easier navigation. –  Steve Fallows Sep 26 '11 at 0:43
show 6 more comments

I do this because I'm often communicating intent to myself, or essentially putting in a convenient bookmark for things like "Data cleaning begins here". Usually under that title is a brief little bit about the logic of what I'm doing and why.

I like redundancy. If I lose my lab notebook for one reason or another, or have to revisit code I wrote years ago, I dislike having to piece together what I was doing and why I was doing it. If at least some of that logic is in the code, its documented enough for me to at least work with it again.

I think part of my inclination towards it is a fair amount of my programming is statistical in nature, and thus somewhat repetitive. Whereas there might be a few pieces of code where I've got a helpfully named function to search for, I might have several dozen fairly similar uses of something like a general linear model function. It's useful to be able to go and find which of those was the "how sensitive are the results to Choice A vs. Choice B or C" code, and which was something else. That's often sped up by titles.

share|improve this answer
add comment

I find it interesting how many people dislike the practice without really being able to articulate why. The reason comments like that are frowned on is they are a sign you have violated the single responsibility principle. That specific name is usually only used in an OO context, but the general concept is also called cohesion and applies to other paradigms. Schools don't usually teach those sorts of design principles until toward the end of a degree program, if at all. In fact, some teachers mandate its violation in order to make things easier to grade by cramming everything into one file. Therefore, your freshman ignorance is excusable, and the fact you noticed "something" wrong and tried to clarify with comments is even laudable under the circumstances, but in general it's better to fix an unclear design rather than try to paper over it with comments.

share|improve this answer
add comment

I look at these things as a way to make the code clearer or not. If you can tell based on the methods in the file what each part is then there is no need however if you have to have multiple sections then it can be useful. Perhaps when a code file gets too large it needs to be broken down which might reduce the need for such comments.

I would say if working within a team to come up with a standard so you are all at least coding and commenting the same way so looking at the code becomes easier.

share|improve this answer
add comment

I do that all the time. Both to mark what the code is doing, and probably more importantly, as you said, to make it easy to scan & find a chunk of code. Sometimes, also, I'll write down an involved process in comments, and 'fill in' the code under the comments as I go.

share|improve this answer
6  
+1 - clarity is a good thing. I disagree with the approved answer saying this is a code smell. If it adds clarity - do it. –  quickly_now Sep 25 '11 at 9:19
2  
If it violates OAOO, then don't do it. It's redundant, and tends to get out of sync with the code that it documents. Put the code into a function and name the function with what it does. Modern IDE's make it easy to change the function name and update all references. That way all instances stay up to date. –  Scott Whitlock Sep 25 '11 at 17:22
2  
+1 from me. In large code files, I like to have more than just whitespace separating logical sections. Yes, I think that if your function is loooooong then you need to split it up, but I find it a lot easier to read if parts are separated by comments. –  anthony-arnold Sep 26 '11 at 0:00
add comment

I think that is useful in situations where you have gigantic source files with dozens of functions and you can loosely organize them into chunks like that. I'm not saying I like that better than smaller, more focused source files however...

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.