Good Comments and Bad Comments in your Program

Are comments needed in your programs? If your code is very clear and expressive, then you won’t ideally need comments. By naming your identifiers correctly you can avoid the need for comments in lot of places within your code. So why learn about writing good comments? Due to reasons including the limitations in expressiveness of a programming language, we may have to still use comments, and for these use cases we will need to learn to write good comments.

 

Good comments

Good comments include legal comments like copyright and authorship, informative comments that provide additional useful info regarding the usage, explanation of intent,  extra clarification, warning of consequences, TODO comments, amplify the importance of something and Javadoc in Public APIs. However you should try to explore if any better and alternatives exist and whether it will be applicable for your use case. For instance, well written unit tests can even avoid the need for JavaDocs.

 

Bad comments 

Bad comments include incomplete comments added just because you feel or the process requires it, redundant comments that are not more informative than the code, misleading comments that are not fully accurate, mandatory comments as a rule for functions, variables etc., journal or change log comments or attributions or commented out code which are all no more required with the use of source control systems, overuse of position marker comments, closing brace comments to cover-up larger functions, comments with too much information, comments with unobvious connection with code where comment itself will need as explanation and even javadocs in non-public code.

 

More recommendations on using comments

  1. Code is always the truth. You can also supplement it with well written unit tests to explain the usages. Well written unit tests can even avoid the need for JavaDocs.

  2. It is better to have not comments at all than inaccurate comments, as inaccurate comments may mislead. There are many reasons for its inaccuracy including comments not always following the code changes and evolution.

  3. Don’t write bad code and spend time in explaining it through comments; instead spend extra time in writing good code and less time for writing comments. Clean code with fewer comments is always better that bad code with lots of comments.

  4. When writing legal comments we should try not to put everything into comments; instead we should try to refer to standard license or other external documents.   

  5. HTML Comments make the code difficult to read; if the comment will be extracted by a tool to show in a webpage, the tool should do the formatting and not the programmer.

  6. You should not comment about some other parts on the system from a comment as there is no guarantee that this comment will be updated when the other part is modified. 

References and notes: 

This note is based on the book “Clean Code” by “Robert C. Martin”. The chapter ‘Comments’ explains all these tips in detail along with examples.

For syntax and rules for comments in Java, refer to javajee.com/comments-in-java.

Quick Notes Finder Tags

Activities (1) advanced java (1) agile (3) App Servers (6) archived notes (2) Arrays (1) Best Practices (12) Best Practices (Design) (3) Best Practices (Java) (7) Best Practices (Java EE) (1) BigData (3) Chars & Encodings (6) coding problems (2) Collections (15) contests (3) Core Java (All) (55) course plan (2) Database (12) Design patterns (8) dev tools (3) downloads (2) eclipse (9) Essentials (1) examples (14) Exception (1) Exceptions (4) Exercise (1) exercises (6) Getting Started (18) Groovy (2) hadoop (4) hibernate (77) hibernate interview questions (6) History (1) Hot book (5) http monitoring (2) Inheritance (4) intellij (1) java 8 notes (4) Java 9 (1) Java Concepts (7) Java Core (9) java ee exercises (1) java ee interview questions (2) Java Elements (16) Java Environment (1) Java Features (4) java interview points (4) java interview questions (4) javajee initiatives (1) javajee thoughts (3) Java Performance (6) Java Programmer 1 (11) Java Programmer 2 (7) Javascript Frameworks (1) Java SE Professional (1) JPA 1 - Module (6) JPA 1 - Modules (1) JSP (1) Legacy Java (1) linked list (3) maven (1) Multithreading (16) NFR (1) No SQL (1) Object Oriented (9) OCPJP (4) OCPWCD (1) OOAD (3) Operators (4) Overloading (2) Overriding (2) Overviews (1) policies (1) programming (1) Quartz Scheduler (1) Quizzes (17) RabbitMQ (1) references (2) restful web service (3) Searching (1) security (10) Servlets (8) Servlets and JSP (31) Site Usage Guidelines (1) Sorting (1) source code management (1) spring (4) spring boot (3) Spring Examples (1) Spring Features (1) spring jpa (1) Stack (1) Streams & IO (3) Strings (11) SW Developer Tools (2) testing (1) troubleshooting (1) user interface (1) vxml (8) web services (1) Web Technologies (1) Web Technology Books (1) youtube (1)