Code comments and documentation explain what a program does, how it works, and why certain decisions were made. Good documentation makes code easier to understand, maintain, and debug — both for you when you return to it later and for anyone else who needs to work with your code.

Why do programs need comments and documentation?

Imagine writing a shopping list today and trying to understand it six months later with no memory of what the abbreviations meant. Code has the same problem. Even experienced programmers forget what a section of their own code does if they return to it weeks later without notes.

Comments serve three main audiences:

  • Your future self — the single biggest beneficiary
  • Other developers — teammates, teachers, or examiners
  • Automated tools — IDEs and documentation generators can extract docstrings to create reference guides automatically

The KS3 national curriculum expects students to "evaluate and improve" their programs — and a program with no comments is nearly impossible for anyone else to evaluate fairly.

What is an inline comment?

An inline comment is a short note on the same line as code, or on the line immediately above it, explaining what that line or block does. In Python, comments begin with a # character.

# Calculate the area of a rectangle
area = length * width          # width is measured in centimetres

# Check whether the student has passed
if score >= 60:
    print("Pass")              # Pass threshold set by department policy

What makes a good comment?

Good comment Weak comment
# Reverse the list before sorting to handle duplicates # Reverse the list
# Use integer division to avoid float rounding errors # Divide x by y
# PASS_MARK agreed with head of year — do not change # threshold = 60

Comments should explain the why, not just repeat the what. If the code itself is already clear (total = total + score), a comment saying "add score to total" adds nothing. A comment saying "running total is used later to calculate the class mean" adds real value.

What is a docstring?

A docstring (documentation string) is a multi-line comment placed at the start of a function, class, or module. It describes the purpose, parameters, and return value of the subroutine.

In Python, docstrings use triple quotes ("""):

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

    Parameters:
        scores (list): a list of numeric scores

    Returns:
        float: the mean average, or 0 if the list is empty
    """
    if len(scores) == 0:
        return 0
    return sum(scores) / len(scores)

Docstrings are accessible at runtime via help(calculate_average), making them especially useful in larger projects. They are a step up from inline comments because they are structured and standardised.

What are naming conventions, and why do they count as documentation?

Naming variables, functions, and constants descriptively is a form of self-documenting code — the names themselves explain what the code does.

Poor name Better name Why it helps
x student_age Immediately tells the reader what the value represents
f(n) calculate_factorial(number) Function name reveals its purpose and parameter meaning
60 PASS_MARK = 60 Named constant makes the meaning of the value explicit
lst exam_scores Describes the contents of the list

The Python convention for naming is:

  • Variables and functions: lowercase_with_underscores (snake_case)
  • Constants: ALL_CAPS_WITH_UNDERSCORES
  • Classes: CapitalisedWords (PascalCase)

Consistent naming means that even without comments, a reader can often understand what a function does just from its name and parameter names.

What is technical documentation?

Technical documentation is written for programmers and developers. It goes beyond inline comments to describe the overall system: what it does, how it is structured, how to install and run it, and how each module or function fits together.

Common types of technical documentation include:

Document type What it contains
README Overview of the project, setup instructions, basic usage
API reference List of all functions/classes with parameters, return values, and examples
Architecture diagram Visual overview of how modules connect
Version history / changelog Record of what changed in each version

At KS3 and GCSE, you are unlikely to produce a full API reference, but writing a clear README for your programming project — explaining what it does, how to run it, and any known limitations — is a good habit that examiners reward.

What is user documentation?

User documentation is written for people who use the program, not those who build it. It focuses on what to do rather than how the code works.

Examples of user documentation:

  • A user manual or help guide
  • On-screen tooltip text
  • A "how to get started" tutorial

The key distinction: if your audience is technical (programmers), write technical documentation. If your audience is non-technical (end users), write user documentation. A good project might have both.

How much commenting is too much?

Over-commenting is as unhelpful as under-commenting. A comment on every single line makes code harder to read, not easier. Aim to:

  • Comment complex or non-obvious logic
  • Document every subroutine (purpose, parameters, return value)
  • Explain any "magic numbers" or unusual decisions
  • Leave obvious, self-explanatory code uncommented
i = i + 1   # Increment i by 1  ← unnecessary; the code says this already

Frequently asked questions

Will I lose marks in a GCSE exam if my code has no comments?

Yes — most GCSE programming assessment mark schemes include criteria for readability and maintainability, which include appropriate use of comments and descriptive identifiers. Even if your program runs correctly, you may lose marks in the "evaluation" or "quality of code" section if it is undocumented. Check your exam board's mark scheme for exact weightings.

Should comments be written before or after the code?

Either — but many programmers write a brief comment explaining what a section should do before writing the code, as a planning step. This is similar to writing pseudocode first and then translating it into a programming language. Returning to add comments after the code is written is also fine, provided you do not skip this step.

What is the difference between a comment and a docstring in Python?

A comment uses # and is for human readers only — Python ignores it completely at runtime. A docstring uses """triple quotes""" and is stored as the __doc__ attribute of the function or module, making it accessible to the help() function and documentation generators. Use comments for explanatory notes within the code body, and docstrings for formal subroutine descriptions.

Do professional programmers really comment their code?

Yes — and not nearly enough, according to most programmers looking at other people's code. Open-source projects, professional codebases, and team environments all rely heavily on documentation. The industry consensus is that code is read far more often than it is written, so investing time in good comments pays dividends throughout the life of a project.

Want to develop clean, well-documented coding habits from KS3? Professor Turing at aitutors.me will guide you through every project step by step.