/* about the worthlessness of comments in clean code */
Created by Björn Kimminich / @bkimminich
"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. |
q.e.d. |
"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.
"Across all Java projects on Open Hub, 31% all source code lines are comments. For Code Kata: Trading Card Game (TCG), this figure is 1%. This lack of comments puts Code Kata: Trading Card Game (TCG) among the lowest 10% of all Java projects on Open Hub."
"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."
@author
tags 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!