#nocomments
TRANSCRIPT
// NO COMMENT!/* about the worthlessness of comments in clean code */
Created by / Björn Kimminich @bkimminich
Follow @bkimminich Tweet 2 Follow @bkimminich 72 Star 1
BJÖRN KIMMINICHIT Architect & Security Officer @ Performing 2-day @ KNLecturer for Software Development @ Read and watched >32 episodesRevenant speaker at , et al.
Kuehne + NagelClean Code Training Workshops
Nordakademieboth books Clean Code
Clean Code Days JavaLand
NARRATIVE ARC OF THIS TALK
1. Scientific Exposition2. Rising Action Examples3. Trademark-protected Climax4. Bonus Climax instead of Falling Action5. RaaTYS (Resolution-as-a-Thank-You-Slide)
5. RaaTYS (Resolution-as-a-Thank-You-Slide)
UNCLE BOB DISLIKES COMMENTS"Comments are, at best, a necessary evil."
STUDENTS LOVE EXTENSIVE COMMENTSAND I CAN PROVE IT!
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.
* ALSO LIKES COMMENTSOPEN HUB"A high number of comments might
indicate that the code is well-documentedand organized, and could be a sign of a
helpful and disciplined developmentteam."
*Open Hub (formerly Ohloh.net) is an online community and public directory of free and open source software.
I'M IN THE WORST 10%OPEN HUB"Across all Java projects on Open Hub,
31% all source code lines are comments.For ,
this figure is 1%. This lack of commentsputs among the lowest 10% of all Java projects
on Open Hub."
Code Kata: Trading Card Game (TCG)
Code Kata: Trading Card Game (TCG)
* GOT IT RIGHT!SONARQUBE"If the source code needs too many
comments, it either means that it does notrespect coding standards (naming
conventions, design, etc.) or it is toocomplex."
*SonarQube (formerly Sonar) is an open platform to manage code quality.
THIS IS IN LINE WITH UNCLE BOB"The proper use of comments is to
compensate our failure to express ourselfin code."
GOES EVEN FURTHERSONARQUBE"Time consuming maintenance [...] may
lead to comments that are no longer up todate. Then comments go against their
primary goal: they mislead the developerwho will spend more time understanding
the source code."
AGAIN IN SYNC WITH UNCLE BOB"Inaccurate comments are far worse than
no comments at all."
ENOUGH OF THE "SCIENTIFIC" EXPOSITION!Let's rise the action with some examples, shall we?
BAD COMMENTS MumblingRedundant CommentsMisleading CommentsMandated CommentsJournal CommentsNoise CommentsScary NoisePosition Markers
Closing Brace CommentsAttributions and BylinesCommented-Out-CodeNonlocal InformationToo much InformationInobvious ConnectionFunction HeadersJavadoc in nonpublic Code
MUMBLING I
MUMBLING II
MUMBLING III
MUMBLING IV
REDUNDANT COMMENTS I
REDUNDANT COMMENTS II
REDUNDANT COMMENTS III
REDUNDANT COMMENTS IV
MISLEADING COMMENTS
THE BATMAN MODE™ METAPHORWhen there is a mystery or crime to be solved, Batman will
utilize his brain and all kinds of fancy gadgets to get itdone! He will analyze, investigate and deduce until he has
the answer. For him as a costumed Super Hero Detective it'spart of the job! Software engineers should never have to go
into Batman Mode™ to investigate comments!
WHAT POSSIBLE CONCLUSIONS ARE THERE?
There was a repaint happening some commits ago. The comment just got obsolete!There was a repaint happening some commits ago. That it's gone was an accident!There was no a repaint happening so far. But it should have been added by now!The repaint is still happening as a hidden side effect somewhere in the code!The developer actually wanted to type // repeat for all calendar days!
MANDATED COMMENTS
JOURNAL COMMENTS
NOISE COMMENTS
SCARY NOISE
POSITION MARKERS
EXCEPTION: GOOD POSITION MARKERSIf 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 BRACE COMMENTS I
CLOSING BRACE COMMENTS II
CLOSING BRACE COMMENTS III
ATTRIBUTIONS AND BYLINES I
ATTRIBUTIONS AND BYLINES II
COMMENTED-OUT-CODE I
COMMENTED-OUT-CODE II
COMMENTED-OUT-CODE III
NONLOCAL INFORMATION I
NONLOCAL INFORMATION II
TOO MUCH INFORMATION
INOBVIOUS CONNECTION
FUNCTION HEADERS
JAVADOC IN NONPUBLIC CODE
AND NOW FOR SOMETHINGCOMPLETELY DIFFERENT
(Intentionally unexpected intermission in the narrative arc)
GOOD COMMENTS Legal CommentsPublic API JavadocInformative CommentsExplanation of IntentClarificationWarning of ConsequencesTODO Comments
LEGAL COMMENTS
PUBLIC API JAVADOC
INFORMATIVE COMMENTS I
INFORMATIVE COMMENTS II
EXPLANATION OF INTENT I
EXPLANATION OF INTENT II
CLARIFICATION I
CLARIFICATION II
WARNING OF CONSEQUENCES I
WARNING OF CONSEQUENCES II
TODO COMMENTS I
TODO COMMENTS II
TODO COMMENTS III
LEFT-OVER TODO COMMENTS
BUT YOU PROMISED US A CLIMAX!!!Closing a talk about how bad most comments are with good
examples seems pretty anticlimactic! I guess we needsomething climactically bad to get back on track now...
CLIMAX: UNCAMELCASING™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.
UNCAMELCASING™ EXAMPLE SKILL LEVEL WHITE BELT
UNCAMELCASING™ EXAMPLE SKILL LEVEL GREEN BELT
UNCAMELCASING™ EXAMPLE SKILL LEVEL BROWN BELT
UNCAMELCASING™ EXAMPLE SKILL LEVEL BLACK BELT
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!
BONUS CLIMAX: JAUTODOC"JAutodoc is an Eclipse Plugin for
automatically adding Javadoc and fileheaders to your source code. It optionallygenerates initial comments from element
name by using Velocity templates forJavadoc and file headers."
// NO COMMENT!
THANKS FOR YOURATTENTION...
...and for not writing comments unless you absolutely have to!
...and for deleting all bad comments you come across from now on!
...and for not using UnCamelCasing™ to create documentation!
...and for never installing/immediately uninstalling JAutodoc!
BY BJÖRN KIMMINICH / KIMMINICH.DEThese slides are publicly available on and .
Copyright (c) 2015 Björn Kimminich - Created with - The HTML Presentation Framework
Most code examples shown in this presentation are from real-life project code. The @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 softwareengineers were harmed during or after the creation of this presentation! Please consider the environment before printing this slide deck!
GitHub Slidesharereveal.js