/* about the worthlessness of comments in clean code */
"Comments are, at best, a necessary evil."
|Professors often like extensive documentation.|
|Professors often promote comments as documentation.|
|Extensive documentation leads to better grades.|
|Students love to get better grades.|
"A high number of comments might indicate that the code is well-documented and organized, and could be a sign of a helpful and disciplined development team."*Open Hub (formerly Ohloh.net) is an online community and public directory of free and open source software.
"If the source code needs too many comments, it either means that it does not respect coding standards (naming conventions, design, etc.) or it is too complex."*SonarQube (formerly Sonar) is an open platform to manage code quality.
"The proper use of comments is to compensate our failure to express ourself in code."
"Time consuming maintenance [...] may lead to comments that are no longer up to date. Then comments go against their primary goal: they mislead the developer who will spend more time understanding the source code."
"Inaccurate comments are far worse than no comments at all."
Let's rise the action with some examples, shall we?
When there is a mystery or crime to be solved, Batman will utilize his brain and all kinds of fancy gadgets to get it done! He will analyze, investigate and deduce until he has the answer. For him as a costumed Super Hero Detective it's part of the job! Software engineers should never have to go into Batman Mode™ to investigate comments!
// repeat for all calendar days!
If you are using some graphical UI editor or other code generator, the position markers they introduce are fine! Removing them would most likely break stuff!
Closing a talk about how bad most comments are with good examples seems pretty anticlimactic! I guess we need something climactically bad to get back on track now...
The art of splitting class/method names into Javadoc while providing zero additional information. There are different skill levels of this art comparable to belts in martial arts.
|It is impossible to reach a black belt in UnCamelCasing™...|
|...at least with manually writing code comments, that is!|
|The real "pro" UnCamelCasers™ go even further...|
|...and automate the UnCamelCasing™ process entirely!|
"JAutodoc is an Eclipse Plugin for automatically adding Javadoc and file headers to your source code. It optionally generates initial comments from element name by using Velocity templates for Javadoc and file headers."
@authortags or other personal data have been anonymized in order to protect the authors from prosecution by Clean Code zealots or other Quality Assurance authorities. No software engineers were harmed during or after the creation of this presentation! Please consider the environment before printing this slide deck!