Documentation and Type Hints

Writing Clear Code

Coding isn’t just about making the computer do something; it’s about telling other humans (including your future self) what your code does. Today we’ll learn two essential tools for professional Python developers: Docstrings and Type Hints.

Docstrings (Documentation Strings)

A Docstring is a special string used as the first statement in a function. It describes what the function does.

1
2
3
4
5
6

def calculate_area(radius):
    """Calculates and returns the area of a circle."""
    return 3.14 * (radius ** 2)

# You can access a function's docstring like this:
print(calculate_area.__doc__)

Best Practices:

1. Wrap the string in triple quotes """.
2. Start with a capital letter and end with a period.
3. Be concise but descriptive.

Type Hints

Python is a “dynamically typed” language, meaning variables can change types. However, you can add Type Hints to suggest what type of data a function should expect and return.

1
2
3
4
5
6
7
8

# name should be a string (str)
# age should be an integer (int)
def greet(name: str, age: int):
    print(f"Hello {name}, you are {age} years old.")

# Return types are indicated with ->
def add(x: int, y: int) -> int:
    return x + y

Why use them?

• Clarity: It’s easier to see how to use a function.
• Tooling: Code editors (like VS Code) can show you warnings if you pass the wrong type.
• Auto-complete: Helps your editor suggest correct methods.

Bringing it Together

Professional Python code usually combines both:

1
2
3

def get_discounted_price(price: float, discount: float) -> float:
    """Calculates the final price after applying a percentage discount."""
    return price * (1 - discount)

Interactive Practice

Try writing a function is_even that takes an integer and returns a boolean. Add a docstring and type hints!