Published: Nov 06 2013 / 08:49
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!
Html tags not supported. Reply is editable for 5 minutes. Use [code lang="java|ruby|sql|css|xml"][/code] to post code snippets.
Advertising - Terms of Service - Privacy - © 1997-2014, DZone, Inc.