June 15, 2023

Writing Clear and Concise Comments in C and Python Code

Comments in code serve as a form of documentation, providing insights into the logic and purpose of the code. Well-written comments not only help other developers understand the code but also aid in maintaining and troubleshooting it. In this post, we’ll delve into the best practices for writing clear and concise comments in C and Python code, with extensive examples in both languages.

C Code Comments

Single-Line Comments

In C, single-line comments start with // and continue until the end of the line. They are ideal for brief explanations or annotating specific lines of code:

1

int result = 0;  // Initialize result to 0

Multi-Line Comments

Multi-line comments in C are enclosed within /* */ and are useful for providing more extensive documentation, such as function descriptions or algorithmic explanations:

1
2
3
4
5
6
7
8
9

/*
 * Function to calculate the sum of two numbers
 * Parameters: num1 - the first number
 *             num2 - the second number
 * Returns: The sum of num1 and num2
 */
int sum(int num1, int num2) {
    return num1 + num2;
}

Inline Comments

Inline comments should be used sparingly and only when necessary to clarify complex or non-obvious code. They should explain why the code is written a certain way, not what the code is doing:

1

int x = 10;  // Compensating for edge case where x must be initialized

Python Code Comments

Single-Line Comments

In Python, single-line comments start with # and are used for short, inline explanations:

1

total = 0  # Initialize total to 0

Multi-Line Comments

While Python does not have a direct multi-line comment syntax, using triple quotes for strings allows for creating multi-line comments. This is often used for docstrings, which serve as inline documentation for functions, classes, and modules:

1
2
3
4
5
6
7
8

"""
Function to calculate the product of two numbers
Parameters: num1 - the first number
            num2 - the second number
Returns: The product of num1 and num2
"""
def product(num1, num2):
    return num1 * num2

Docstrings

Docstrings are a key part of Python code comments and serve as a form of inline documentation. They are enclosed in triple quotes and provide explanations for functions, classes, and modules:

1
2
3
4
5
6
7
8

def greet(name):
    """
    Function to greet the user by name
    Parameters:
        name - the name of the person to greet
    Returns: A greeting message for the given name
    """
    return f"Hello, {name}!"

Best Practices for Writing Clear and Concise Comments

1. Be Clear and Descriptive: Comments should explain the intent behind the code, focusing on why rather than what. This helps developers understand the reasoning and context behind the implementation.

2. Avoid Redundancy: Comments should complement the code, not duplicate it. They should provide additional insights that are not immediately evident from the code itself.

3. Maintain Consistency: Follow a consistent commenting style throughout the codebase, ensuring that comments are uniform and easy to understand for all developers.

4. Update Comments Alongside Code Changes: Whenever the code undergoes modifications, ensure that the relevant comments are updated to reflect the changes accurately.

5. Use Meaningful Naming: Whenever possible, use expressive and meaningful variable and function names that reduce the need for excessive commenting.

By following these best practices and using the provided examples as a guide, developers can create clear and concise comments in their C and Python code. Remember, well-documented code is not only a sign of professionalism but also a valuable asset for the entire development team.

Happy coding!

➡️ libc - ctype.h functions

⬅️ libc - strlen()

Go back to Posts.