A coworker of mine believes that any use of in-code comments (ie, not javadoc style method or class comments) is a code smell. What do you think?
locked by Yannis Rizos♦ Nov 27 '12 at 20:12
This question exists because it has historical significance, but it is not considered a good, on-topic question for this site, so please do not use it as evidence that you can ask similar questions here. This question and its answers are frozen and cannot be changed. More info: FAQ.
closed as not constructive by Yannis Rizos♦ Nov 27 '12 at 20:11
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or specific expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, see the FAQ for guidance.
No, comments are not a code smell, they are just a tool that can be abused.
Examples of good comments:
// I think this is in cm. Further investigation needed!
// This is a clever way of doing X
// The list is guaranteed to be non-empty here
|show 4 more comments|
However code that cannot be understood at all it a much bigger code smell…
Most of the words have been taken out of my mouth. But I suppose to sum it all up: the point of comments is to give a high-level description/explanation of what the code is doing.
Moreover, here are a few examples of how I use comments:
No one said this so far in this thread, so I will:
Type names, variable names, function names, method names and comments are just metadata about your code, and has nothing to do with the machine code that the compiler generates (except the names of the exported and debug symbols of course).
Type names and variable names are your nouns, function and method names are your verbs, with these you describe steps to be done. Comments are for everything else.
Comments may bacome obsolete, if not updated, but variable and function names can become obsolete too. I recently encountered a
It doesn't seem like too many answers consider programming in teams. I'm a senior developer and I tend to write comments aimed at explaining what is otherwise simple for me to understand.
I see it as a form of posthumous team communication or education. I encourage the team to look through code they are using, but maybe haven't written to understand it better.
A couple of examples just from this week (PHP code):
I'd hope the name
Same set of code:
There's an expectation that our developers know PHP, but not that they understand the Linux OS we are using for hosting.
So, I find these comments to actually increase the overall efficiency of our team for the very little time it takes to write them.