Helping Understand Code

Comments act like notes explaining code, making it easier for both current and future developers to understand what the code does and why. They’re like guideposts, pointing out important parts and saving time when someone needs to work with the code later.

Explaining Complex Stuff

In tricky parts of code, like complex algorithms, comments are like tour guides. They explain how things work, why they’re done a certain way, and how to handle special cases. This makes it easier for everyone to follow along and avoids confusion.

Teamwork and Learning

Comments are like sharing knowledge with your team. They help developers collaborate by explaining ideas, sharing insights, and making sure everyone’s on the same page. They’re also great for new team members, giving them a roadmap to understand the code faster.

Be Brief and Why-Focused

• Keep comments short, focusing on explaining why the code exists rather than how it works.
• Avoid redundant comments and emphasise the purpose or intention behind your code.

Use Simple Language

• Write comments in a way that’s easy for all developers to understand.
• Choose clear variable names and explain any technical terms you use within the comment.

Update Comments with Code Changes

• Whenever you change your code, make sure to update the associated comments.
• This ensures comments stay accurate and helpful, avoiding confusion for future developers.

Strategic Comments

• Use comments where they add value, explaining complex logic or non-obvious parts of your code.
• Avoid over-commenting; focus on clarity and relevance.

Block Comments

Block comments are multi-line comments typically used to provide an overview, explanations of sections of code, or to temporarily disable code.

• Providing context for complex algorithms or logic.
• Explaining the purpose of a function, class, or module.
• Disabling a section of code for debugging or testing purposes.

"""
This function calculates the Fibonacci sequence up to n terms.
It utilises memoization for improved performance.
"""

def fibonacci(n):
    # Check if n is less than or equal to 1
    if n <= 1:
        return n
    # Recursive calculation of Fibonacci sequence
    else:
        return fibonacci(n-1) + fibonacci(n-2)

Inline Comments

Inline comments are short comments placed on the same line as code to provide clarification or context for specific lines of code.

• Clarifying complex or non-obvious code.
• Providing brief explanations for variable assignments or function calls.
• Documenting edge cases or unusual behavior.

result = calculate_total_cost(order)  # Calculate total cost including tax and shipping

Documentation Comments

Documentation comments, also known as docstrings, are used to provide detailed explanations of functions, classes, modules, or packages. They often follow a specific format and can be automatically extracted to generate documentation.

• Describing the purpose, parameters, return values, and usage examples of functions or methods.
• Documenting classes, including their attributes, methods, and inheritance hierarchy.
• Providing an overview of modules or packages and their contents.

def calculate_total_cost(order):
    """
    Calculate the total cost of an order including tax and shipping.

    :param order: A dictionary representing the order with keys 'items' (list of items), 'tax_rate' (float), and 'shipping_cost' (float).
    :return: The total cost of the order as a float.
    """
    # Calculate subtotal
    subtotal = sum(item['price'] for item in order['items'])
    # Apply tax
    tax_amount = subtotal * order['tax_rate']
    # Add shipping cost
    total_cost = subtotal + tax_amount + order['shipping_cost']
    return total_cost

TODO Comments

TODO comments are used to mark areas of code that require further attention, such as unfinished tasks, improvements, or known issues. They serve as reminders for developers to address specific tasks in the future.

• Identifying areas of code that need to be implemented or completed.
• Noting areas where improvements or optimisations can be made.
• Highlighting potential bugs or edge cases that need to be addressed.

# TODO: Implement error handling for invalid input
def parse_input(input_data):
    pass

Redundant or Misleading Comments

• Don’t say what’s obvious in the code. For example, writing // increment x by 1 above x++; is unnecessary.
• Ensure comments accurately describe the code. Wrong or outdated comments can confuse developers.

Neglecting Comments Altogether

• Skipping comments makes code hard to understand, especially for others. It slows down collaboration and can cause mistakes.
• Comments should be part of coding habits, not an afterthought.

Outdated Comments

• Update comments when you change code. Old comments can mislead and cause errors.
• Use tools like version control to track changes in both code and comments.

Tools and IDE Features

• IDEs: Programs like Visual Studio Code and IntelliJ IDEA have built-in features to help write and format comments neatly.
• Documentation Generators: Tools like Javadoc and Doxygen automatically create documentation from specially formatted comments, making it easier to understand code.
• Linters and Analysis Tools: Tools like ESLint can check if comments follow specific rules, ensuring they’re clear and consistent.

Version Control Systems (VCS) Role

• Commit History: Git tracks changes to both code and comments over time, helping developers understand why comments were added or changed.
• Branching and Merging: Teams can use branches in Git to work on comment changes separately from code changes, keeping things organised.

Establishing Team Guidelines

• Consistent Formatting Standards: Agree on how comments should look across the team, like how long they should be or where they should go.
• Documentation Conventions: Decide on rules for documenting code features, like what to say about functions or variables.
• Regular Review: Make sure to check and improve comments regularly during code reviews, asking for feedback from team members.