Link Details

Link 1061329 thumbnail
User 1087079 avatar

By KieranF
Published: Nov 06 2013 / 08:49

A rough guide to the best way to develop effective comments and documentation for you code.
  • 12
  • 0
  • 1012
  • 840


Add your comment
User 1061733 avatar

Plow replied ago:

0 votes Vote down Vote up Reply

Thank you for this well thought out opinion. However, I would challenge this and say think of comments as a failure to make the code readable and a necessary evil at best (mostly when dealing with 3rd party libraries). With this commenting approach, you are forced to maintain code AND what could be some pretty intense comments. Remember to keep this in mind - the only place for truth is the code and only the code. Comments can say one thing and the code can do another. I have experienced this many times. I believe a better approach is to refactor the code to the point where the intent is very obvious without the use of comments. This is the model I follow and it serves me so much better than any documentation. The key is refactor. Code doesn't need to start out perfectly. Like I said, sometimes comments are necessary but a good craftsman should be asking themselves, is there a way to make this so comments aren't needed? Perhaps the method name can be named to reflect its purpose more clearly. Perhaps this method is breaking the 'only do one thing' rule and needs to be refactored to separate, smaller methods with descriptive names. I would much rather read and maintain an uncluttered class where methods clearly unfold the story in greater and greater detail, than reading down a class cluttered with comments and hard-to-decipher code. Thank you again and happy coding!

Add your comment

Html tags not supported. Reply is editable for 5 minutes. Use [code lang="java|ruby|sql|css|xml"][/code] to post code snippets.

Apache Hadoop
Written by: Piotr Krewski
Featured Refcardz: Top Refcardz:
  1. Play
  2. Akka
  3. Design Patterns
  4. OO JS
  5. Cont. Delivery
  1. Play
  2. Java Performance
  3. Akka
  4. REST
  5. Java