Course contentsShow
← Computer Science
Lesson 192 of 2,8725. Functions and ModularityFree lesson

Function Documentation

Understanding how to document function purpose, parameters, and return values using comments.

Function Documentation

What you'll learn: How to write clear comments that explain what a function does, what inputs it expects, and what it returns.

Why Document Functions?

When you write a function, you know exactly what it does—but someone else reading your code (or even you in six months) might not. Function documentation is like leaving a helpful note that explains:

  • What the function accomplishes
  • What parameters it needs (and what they represent)
  • What value it returns (if any)

Think of it like labeling a tool in a toolbox. The hammer doesn't explain itself—you add a label so anyone can grab the right tool for the job.

How to Document a Function

Most languages use comments placed directly above or inside the function. Here's the typical structure:

# Calculates the area of a rectangle
# Parameters: width (number), height (number)
# Returns: area as a number

function calculateArea(width, height)
    return width * height

Even though we're just using comments (text the computer ignores), we're creating a mini-manual for the function.

What to Include

  1. Purpose: One sentence describing what the function does
  2. Parameters: Name and meaning of each input
  3. Return value: What the function gives back (or note "returns nothing" for void functions)

Good documentation makes your code readable and maintainable. Other programmers (including future you) will thank you for explaining why something exists and how to use it correctly.

Key Takeaway: Function documentation uses comments to clearly describe a function's purpose, parameters, and return value, making code easier to understand and use.