Unit 10 • Lesson 8

Writing Documentation and Comments

Overview

Every professional project includes clear documentation. You'll write descriptive comments and a README file explaining how to install, run, and understand your project, making it accessible to others and demonstrating professional practices.

Beginner 20–25 min

Next: Presenting Your Project All Units

What You Will Learn in This Lesson

By the end of this lesson, you will know:

Comments: Explaining code with inline comments.
Docstrings: Documenting functions and modules.
README files: Writing project documentation.
Best practices: When and how to document code.
Professional documentation: Making code accessible to others.

Why Documentation Matters

Good documentation helps:

You Remember

You'll understand your own code later

Others Understand

Other people can use and modify your code

Show Professionalism

Demonstrates good programming practices

Save Time

Less time explaining how code works

Writing Comments

Comments explain why code does something, not what it does:

Good Comments

# Calculate discount (10% off for students)
discount = price * 0.10

# Validate input before processing
if not user_input.strip():
    raise ValueError("Input cannot be empty")

# Sort tasks by priority (highest first)
tasks.sort(key=lambda t: t['priority'], reverse=True)

Comment Best Practices

Write comments for complex logic, non-obvious decisions, and important details. Don't comment obvious code—good code is self-documenting!

Writing Docstrings

Docstrings document functions and modules:

Docstring Examples

def add_task(tasks, task_name):
    """
    Add a new task to the task list.
    
    Args:
        tasks (list): List of task dictionaries
        task_name (str): Name of the task to add
    
    Returns:
        list: Updated list of tasks
    
    Example:
        >>> tasks = []
        >>> tasks = add_task(tasks, "Buy groceries")
        >>> len(tasks)
        1
    """
    tasks.append({"name": task_name, "completed": False})
    return tasks

Writing README Files

A README explains your project:

README Structure

# Task Manager

A simple command-line task manager for organizing daily tasks.

## Features
- Add new tasks
- View all tasks
- Mark tasks as complete
- Save tasks to file

## Installation
No installation required. Just run:
```
python main.py
```

## Usage
1. Run the program
2. Choose an option from the menu
3. Follow the prompts

## Requirements
- Python 3.7 or higher

Summary

In this lesson, you learned:

Comments: Explain why code does something
Docstrings: Document functions and modules
README: Explain project to users
Best practices: Document complex logic, not obvious code

Remember

Good documentation makes your project professional and accessible. Take time to write clear comments and documentation—future you (and others) will thank you!

End-of-Lesson Exercises

Think about these questions to reinforce what you've learned:

Exercise 1: Documentation

Why is documentation important? What's the difference between comments and docstrings?

Exercise 2: README

What should a README file include? Why is it important for projects?

← Previous Next