Do you write titles in code comments?

Question

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?

Answer 1

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

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

Answer 2

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.

Answer 3

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.

Answer 4

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.

Answer 5

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...

Answer 6

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.