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
- Purpose: One sentence describing what the function does
- Parameters: Name and meaning of each input
- 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.