Best Practices for Code Documentation and Comments: A Guide for Budding Programmers

Introduction

Code documentation and comments are often overlooked by novice programmers, but they are vital components of writing clean, maintainable, and collaborative code. In this guide, we'll explore the best practices for code documentation and comments, aimed at helping budding programmers improve their coding skills and make their code more accessible to others.

Why Are Code Documentation and Comments Important?

Before we dive into best practices, it's crucial to understand the significance of code documentation and comments. Here are a few reasons why they matter:

1. Clarity: Comments help you explain your code's logic, making it easier for both yourself and others to understand.

2. Maintainability: Proper documentation simplifies the process of maintaining and updating code. It allows you to identify areas that need improvement or fixing.

3. Collaboration: When working on a team project, good comments make it easier for team members to understand and work with your code.

4. Learning: If you're a budding programmer, well-documented code can serve as a valuable learning resource.

Now, let's explore the best practices for code documentation and comments.

1. Use Descriptive Variable and Function Names

The first step in writing good code is choosing descriptive names for your variables and functions. Avoid single-letter or cryptic names. Instead, opt for names that clearly convey the purpose and functionality of the code.

Bad:

x = 5

Good:

total_score = 5

2. Comment Every Non-Obvious Section

Whenever you write a piece of code that's not immediately obvious in its purpose or functionality, add a comment to explain it. Comments should provide context and reasoning for the code that follows.

Bad:

# Increment the variable
x = x + 1

Good:

# Increment the total score by 1
total_score = total_score + 1

3. Keep Comments Concise

While it's essential to provide context, avoid writing excessively long comments. Aim for brevity while conveying the necessary information.

Bad:

# This loop iterates through the list of user scores, calculates the average by summing the scores, 
# dividing by the number of scores, and then stores the result in the average_score variable.

Good:

# Calculate the average user score

4. Avoid Redundant Comments

Don't write comments that merely restate what the code does. Instead, focus on why you're doing it or any edge cases that others should be aware of.

Bad:

# This line increments the counter by 1.
counter = counter + 1

Good:

# To keep track of the number of occurrences
counter = counter + 1

5. Update Comments with Code Changes

When you modify your code, remember to update the associated comments. Outdated comments can be more confusing than having no comments at all.

6. Use Docstrings for Functions

In languages like Python, use docstrings to provide detailed information about functions, including their parameters, return values, and usage. Docstrings can be accessed via the built-in help() function.

Example:

def calculate_average(scores):
    """
    Calculate the average of a list of scores.

    Parameters:
    scores (list): A list of numerical scores.

    Returns:
    float: The calculated average score.
    """
    # Function implementation here

7. Readability Matters

Make sure your comments are neatly formatted, follow a consistent style, and are free from grammar and spelling errors. Clean, well-structured comments enhance the readability of your code.

Conclusion

As a budding programmer, embracing code documentation and comments from the outset will set you on the path to becoming a more efficient and effective developer. These best practices will not only help you understand your code but also make it accessible and maintainable for others. Remember that writing good comments is a skill that improves with practice, so keep coding and keep commenting!

Comments

[Jon Randy 🎖️]

Might want to revise the examples somewhat. In section 2, this is 'good':

# Increment the total score by 1
total_score = total_score + 1

Then in section 4, this is marked as 'bad':

# This line increments the counter by 1.
counter = counter + 1

[Alin Pisica]

I pretty much think that he meant it based on the variable's name. In the first example, section 2, total_score is pretty self explanatory by its name, while in the second example you gave, in section 4, counter is not so easy to understand in terms of goals and where it is used (what does it count? apples?), but the comment would give an overview over the fact that it counts the total number of occurrences (as mentioned in the article).

[Jon Randy 🎖️]

I don't think so. The article is about comments, not variable naming. The comments shown here give no more information about the variables' content - they just repeat the name.

[Monty Harper]

The article is about documentation, which encompasses both comments and variable naming. Also, I took each example to be illustrative of a particular point. In point 2, the example went from "bad" to "good" by providing context, while both versions happen to be redundant. In point 4 the example went from "bad" to "good" by removing redundancy. In both cases the code could be further improved by applying both principals. In point 2 the "good" example could be made even better by dropping the comment altogether to remove the redundancy. In point 4 the "good" example could provide even more context with a better variable name (in which case a comment may not be needed), or a more specific comment (occurrences of what?). But I believe the author's intent was to create examples that focus on one issue at a time.

[James saloman]

Got my point..

[Raul Ferreira]

I ended up noticing it and was confused about it too. But the rest of the content is very good, thank you for sharing 🦤.

[Stacy Roll]

I still don't make any comment inside my code because i write it clear. Just junior and trainee make use comments

[Alin Pisica]

Agree to disagree. I love clean code that is not commented. I do not love people who do not add comments just because they think that they write clean code. Yes, as long as everyone is on the same page with the coding style and can be easily understood, comment's are useless, but I would rather have some than none, and I can easily disable them through extensions.

[Jake Espinosa]

Like the commenter above, agree to disagree. Comments shouldn't be overused (and often are), but using them to explain complex code that can't realistically be simplified is a good practice. I'd also argue docstrings are a great thing to have in your code.