Code Grammar — Chapter 2

Enhance Code Communication through Comments

Whoever said code can’t talk, they talk and can talk better with comments!

What are the comments?

In programming, comments are annotations or notes added to the source code of a program. Comments have a special power that no one has in programming, these comments are not executed as part of the program. The main intent of the comment is to provide explanations, documentation, or additional information to developers or anyone reading the code.

Syntax variations:

Get Shantanu kumar’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

In most programming languages, comments are marked by specific symbols. For example:

• In Python, comments start with the # symbol.
• In JavaScript, both // for single-line comments and /* */ for multi-line comments are used.
• In languages like C, C++, and Java, single-line comments start with //, and multi-line comments are enclosed between /* and */.

How to write effective comments?

1. Be Clear and Concise

• Inaccurate comments are far worse than no comments at all, Use clear and simple language to explain complex parts of the code.
• A good comment is a comment you found a way not to write.

2. Explain the Why, Not the What:

• Focus on explaining the purpose or rationale behind a piece of code rather than simply describing what the code does. The “what” is often evident from the code itself.
• Consider the context and explain why a particular approach or solution was chosen.

3. Update Comments with Code Changes:

• The older a comment is, and the farther away it is from the code it describes, the more likely it is to just plain wrong.
• Regularly review and update comments to ensure they remain accurate. Outdated comments can be misleading and counterproductive.

4. Use Descriptive Variable and Function Names:

• Some comments are for giving basic information, but It can be avoided by choosing meaningful names for variables and functions. Well-named entities reduce the need for excessive comments.

5. Avoid Redundant Comments:

• Aim for comments that provide additional insights beyond what’s obvious from the code, Comment probably takes longer to read than the code itself.

6. Consider Future Readers:

• Avoid using overly technical or domain-specific terms without explanation if the audience is unfamiliar with them.
• Comments can be TODO, which explains why the function has a degenerate implementation and what the function’s future should be. Or explain the reason can’t do it at the moment.
• Warn other programmers about certain consequences. With modern languages Ignore attribute can be used here.

7. Use Proper Grammar and Spelling:

• Well-written comments contribute to a positive impression of the codebase.
• If you decide to write a comment, then spend the time necessary to make sure it is the best comment you can write.

8. Comment Complex Algorithms:

• Some comments are to provide the intent behind a decision/implementation.
• Your code includes intricate algorithms or non-trivial logic, use comments to break down the steps and explain the algorithm’s purpose.

9. Use Comment Headers for Sections:

• Divide your code into logical sections and use comment headers to indicate each section’s purpose. This is especially helpful in large files or projects.
• Maintain simplicity in your code structure to negate the need for marker comments or closing braces comments.
• Be mindful of nonlocal comments, which delve into aspects unrelated to the function’s control or implementation. Keep comments directly relevant to the code they accompany, ensuring they enhance understanding without introducing unnecessary distractions.

10. Be Mindful of Code Readability:

• Avoid excessive use of inline comments, as they can clutter the code. Reserve them for particularly important or tricky parts.
• There is a silly rule that says every function must have a Javadoc, comments like this just clutter up the code.
• Comments whose purpose is to make a journal can be avoided by using a version control system like git.
• Keeping commented-out code contributes to code bloat, as other developers may hesitate to remove it.

What comes with comments, and side effects?

1. Verification Challenges:
   While comments offer insights, they can occasionally be inaccurate, posing challenges in confirming their correctness. Verifying the accuracy of comments may become a task on its own.
2. Code Quality Justification:
   Comments often serve as a means to rationalize suboptimal code or insufficient decisions. Ideally, comments should complement code, compensating for our occasional struggles in fully expressing complex ideas through programming.
3. Maintenance Pitfalls:
   Neglected or outdated comments pose risks during code modifications. As code evolves, if comments aren’t kept in sync, they transform from helpful guides into potential sources of confusion, potentially leading to errors in future modifications.