#NoComments

4,467 views

Published on

"Comments are - at best - a necessary evil" (Uncle Bob, "Clean Code") - Over the years I gathered quite a collection of examples for bad code comments. The most precious gems among them I would like to share with you. You will listen in on developer monologues and dialogues, try to analyze cryptic bylines, experience different levels of UnCamelCasing(tm) skill and fight your way through a redundant, useless and misleading inline thicket. You will also hear about well-meant tools and plugins that should not even exist if the motto "No Comment!" would be valued as it should be.

0 Comments
4 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
4,467
On SlideShare
0
From Embeds
0
Number of Embeds
2,353
Actions
Shares
0
Downloads
10
Comments
0
Likes
4
Embeds 0
No embeds

No notes for slide

#NoComments

  1. 1. // 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
  2. 2. BJÖRN KIMMINICH IT Architect & Security Officer @ Performing 2-day @ KN Lecturer for Software Development @ Read and watched >32 episodes Revenant speaker at , et al. Kuehne + Nagel Clean Code Training Workshops Nordakademie both books Clean Code Clean Code Days JavaLand
  3. 3. NARRATIVE ARC OF THIS TALK 1. Scientific Exposition 2. Rising Action Examples 3. Trademark-protected Climax 4. Bonus Climax instead of Falling Action 5. RaaTYS (Resolution-as-a-Thank-You-Slide)
  4. 4. UNCLE BOB DISLIKES COMMENTS "Comments are, at best, a necessary evil."
  5. 5. STUDENTS LOVE EXTENSIVE COMMENTS AND 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.
  6. 6. * ALSO LIKES COMMENTSOPEN HUB "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.
  7. 7. 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 comments puts among the lowest 10% of all Java projects on Open Hub." Code Kata: Trading Card Game (TCG) Code Kata: Trading Card Game (TCG)
  8. 8. * GOT IT RIGHT!SONARQUBE "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.
  9. 9. THIS IS IN LINE WITH UNCLE BOB "The proper use of comments is to compensate our failure to express ourself in code."
  10. 10. GOES EVEN FURTHERSONARQUBE "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."
  11. 11. AGAIN IN SYNC WITH UNCLE BOB "Inaccurate comments are far worse than no comments at all."
  12. 12. SUMS IT UPGEEK & POKE
  13. 13. ENOUGH OF THE "SCIENTIFIC" EXPOSITION! Let's rise the action with some examples, shall we?
  14. 14.  BAD  COMMENTS  Mumbling Redundant Comments Misleading Comments Mandated Comments Journal Comments Noise Comments Scary Noise Position Markers Closing Brace Comments Attributions and Bylines Commented-Out-Code Nonlocal Information Too much Information Inobvious Connection Function Headers Javadoc in nonpublic Code
  15. 15. MUMBLING I
  16. 16. MUMBLING II
  17. 17. MUMBLING III
  18. 18. MUMBLING IV
  19. 19. REDUNDANT COMMENTS I
  20. 20. REDUNDANT COMMENTS II
  21. 21. REDUNDANT COMMENTS III
  22. 22. REDUNDANT COMMENTS IV
  23. 23. MISLEADING COMMENTS
  24. 24. THE BATMAN MODE™ METAPHOR 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!
  25. 25. 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!
  26. 26. MANDATED COMMENTS
  27. 27. JOURNAL COMMENTS
  28. 28. NOISE COMMENTS
  29. 29. SCARY NOISE
  30. 30. POSITION MARKERS
  31. 31. EXCEPTION: GOOD POSITION MARKERS 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!
  32. 32. CLOSING BRACE COMMENTS I
  33. 33. CLOSING BRACE COMMENTS II
  34. 34. CLOSING BRACE COMMENTS III
  35. 35. ATTRIBUTIONS AND BYLINES I
  36. 36. ATTRIBUTIONS AND BYLINES II
  37. 37. EXPLAINSGEEK & POKE COMMENTED-OUT-CODE
  38. 38. COMMENTED-OUT-CODE I
  39. 39. COMMENTED-OUT-CODE II
  40. 40. COMMENTED-OUT-CODE III
  41. 41. NONLOCAL INFORMATION I
  42. 42. NONLOCAL INFORMATION II
  43. 43. TOO MUCH INFORMATION
  44. 44. INOBVIOUS CONNECTION
  45. 45. FUNCTION HEADERS
  46. 46. JAVADOC IN NONPUBLIC CODE
  47. 47. AND NOW FOR SOMETHING COMPLETELY DIFFERENT (Intentionally unexpected intermission in the narrative arc)
  48. 48.  GOOD  COMMENTS  Legal Comments Public API Javadoc Informative Comments Explanation of Intent Clarification Warning of Consequences TODO Comments
  49. 49. LEGAL COMMENTS
  50. 50. PUBLIC API JAVADOC
  51. 51. INFORMATIVE COMMENTS I
  52. 52. INFORMATIVE COMMENTS II
  53. 53. EXPLANATION OF INTENT I
  54. 54. EXPLANATION OF INTENT II
  55. 55. CLARIFICATION I
  56. 56. CLARIFICATION II
  57. 57. WARNING OF CONSEQUENCES I
  58. 58. WARNING OF CONSEQUENCES II
  59. 59. TODO COMMENTS I
  60. 60. TODO COMMENTS II
  61. 61. TODO COMMENTS III
  62. 62. LEFT-OVER TODO COMMENTS
  63. 63. BUT YOU PROMISED US A CLIMAX!!! 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...
  64. 64. 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.
  65. 65. UNCAMELCASING™ EXAMPLE  SKILL LEVEL  WHITE BELT 
  66. 66. UNCAMELCASING™ EXAMPLE  SKILL LEVEL  GREEN BELT 
  67. 67. UNCAMELCASING™ EXAMPLE  SKILL LEVEL  BROWN BELT 
  68. 68. 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!
  69. 69. BONUS CLIMAX: JAUTODOC "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."
  70. 70. // NO COMMENT!
  71. 71. THANKS FOR YOUR ATTENTION... ...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.DE These 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 software engineers were harmed during or after the creation of this presentation! Please consider the environment before printing this slide deck! GitHub Slideshare reveal.js

×