Meh...Most comments I've encountered in my life are written under the assumption that comments can make up for poorly written code.. – Stargazer712 Oct 14 '10 at 20:53
I saw the above comment on this page, and I highly agree with what Stargazer712 said.
So often I hear people talking about commenting code as a 'solution' to making crap code understandable. Using comments in this manner is not a solution, but instead a hacky work-around for the in-ability to produce quality code.
If code is well written and structured, then the amount of comments you need can be greatly reduced, as the code itself would be pretty self explanatory.
Furthermore comments can be misleading and do more harm than good. I've seen many cases where a comment says code does one thing, but its really doing another. Or I've seen bad coders change code, but leave in their old comments which are now totally irrelevant, just making the reader more confused.
I'm not saying comments are bad, but I am saying that they are no excuse to be writing crap code. Sometimes code gets very complex, and its not due to the programmer being bad, but instead because they are heavily optimizing something or they are implementing something that's very involved and tricky. In these cases commenting code is very helpful and justified.
Something I personally don't like to see is a lot of comments in the main .cpp files of a project, mainly because it gets in the way of code. Instead I like comments to be placed in the headers and next to the function prototypes away from the main implementation of the code so that when you are actually looking at the .cpp file, you can focus on the real code instead of seeing a wall of green-text getting in the way.
If they're 1 or 2-liner comments then its fine to put them in the .cpp file, but if you're going to write a paragraph then save it for the .h file because I don't want to see that when I'm trying to understand your code (your real code, not what you 'say' your code does!).
Another thing I see often that newbie coders love to do is write obvious comments. Stuff like "i = 1; // set i to 1", these comments are not at all helpful, and they only serve to bloat code.
Anyways I guess I can rant more, especially about bloated code, but I'll think I'll save that for a future post.
Good code comments itself... to a certain extent. If code is well written, you should only comment to give information someone cannot discern easily from reading the code; or to give background knowledge, or an overview of what the code does.
ReplyDeleteI pretty much agree with all your points above.
My 2c.
Yup I agree with what you said as well.
ReplyDeleteI've never known whether to stuff comments in headers or in cpp files. I've switched between both methods about 20 times in my career so far.
ReplyDeleteSome people really like having headers clean: on larger classes a clean header file can be an extremely useful class diagram and class reference. It's one of the few times the header concept of C++ is more than just annoying red tape. On the other hand, comments in header files are readily exposed to outside coders who do not have access to the cpp contents (something that generally doesn't happen much anymore .. the days of the source-less pre-compiled library are rather defeated).
On the OTHER other hand, comments in cpp files are much closer to the code they detail, so the comments can be more easily maintained along with code changes. Comments in headers tend to fall out of sync much quicker.
Finally all of this applies to 3rd party/utility/class coding only. Internals coding is a different beast, where most comments are placed at the head of .h and .cpp files: the comments typically present rationales for why the code has taken some specific approach to implementing the given task, and may have brief account of specific challenges that have been encountered and circumvented. These things are usually not immediately obvious to someone else who may be looking to modify the code, or may present helpful diagrams of complex algos and tables.
In any case, all modern IDEs have the ability to collapse comments, so I don't worry about the visual appeal aspect much anymore. I do worry for the maintaining accuracy part, so for that reason I've been sticking most of them in cpp files lately.
Well another reason to put the comment in the header next to the prototypes is in my experience visual studio will most of the time find the class/function prototype when you "goto definition" and rarely find the definition.
ReplyDeleteif you are linking to a dll library, you also might be including headers from the project, but don't have access to the .cpp files (or maybe you do but its not part of your main project and you can't look at it so easily).
nowadays some intellisense systems will attempt to show the comment that is written above a prototype when you're typing a function name or hovering over a function. not sure if this works as well if you're commenting in the .cpp file definitions. especially since like i mentioned the intellisense generally sucks at finding member/function definitions.
it is true that comments in the .cpp file are closer to the code. but imo that means if you're going to comment there you should comment very concisely. because imo when someone is looking at the .cpp file they actually are more interested in reading the code instead of reading the high-level explanation of what its attempting to do.
when someone reads the function prototypes on the other hand, they're probably more interested in the high-level explanation.