Skip to main content

Writing Functions with Intent

Why Write Functions? — Code Reuse and Clear Intent​

The Problem: You find yourself writing the same code over and over. A calculation you need in three different places. A data validation check used throughout your script.

The Solution: Write a function once, call it many times. Better yet, write it with such clear intent (type hints + docstring) that other developers (or AI) understand exactly what it does without reading the implementation.

💻 Code Idea: Function as Organized Intent​

Loading Python environment...

Why this matters: The function signature (def add(a: int, b: int) -> int:) tells you everything you need to know: it takes two integers and returns an integer. That's the intent. The docstring explains the purpose. The body is just the implementation.

💬 AI Colearning Prompt​

Ask your AI: "I need a function that takes a list of prices and calculates total cost with 10% tax. What should the type hints be? What should the docstring say? Write just the function signature (def line through docstring, no body yet)."

Expected Understanding: You see that intent comes before implementation. A clear function signature (especially with type hints) lets you think about WHAT you need before HOW to code it.

🎓 Instructor Commentary​

Type hints are not just syntax—they're your contract with other developers and AI. When you write def calculate(items: list[float]) -> float:, you're making a promise: "I accept a list of floats and return a single float." This is incredibly powerful. AI can validate your code against this contract. Other developers know exactly what to pass and what to expect back. Syntax is cheap and forgettable. Semantics—the meaning behind the code—is what matters. Type hints encode semantics directly into your function signature.

Function Definition — The Structure​

Anatomy diagram of Python function signature showing def keyword, function name, parameters with type hints, return type annotation, and docstring structure with clear labeling

Components of a Function:

Loading Python environment...

  • def — Python keyword that starts a function definition
  • function_name — What you call the function (use descriptive names)
  • parameters — Variables the function receives when called
  • Type hints — Tell what type each parameter should be, and what type is returned
  • Docstring — Multi-line string explaining the function's purpose
  • return — Send a value back to the caller

💻 Code Idea: Simple Function with Type Hints​

Loading Python environment...

Key Observation: The type hints (int, str, ->) are hints for humans and type checkers. Python executes the function the same way without them, but they make intent clear.

Type Hints as Intent Specification​

What Type Hints Say: Type hints are your specification. They answer: "What data types should this function receive? What type will it return?"

💻 Code Idea: Type Hints on Complex Parameters​

Loading Python environment...

Reading the Type Hint: numbers: list[float] says "numbers must be a list of floats." Return type -> float says "this function returns a single float."

Docstrings — Communication for Humans and AI​

Purpose: A docstring explains what the function does. It's not a comment about implementation details—it's documentation for the USER of the function.

💻 Code Idea: Well-Documented Function​

Loading Python environment...

Docstring Structure:

  1. One-line summary — What does this function do?
  2. Parameters section — What inputs does it take?
  3. Returns section — What does it return?

Functions with Multiple Parameters and Default Values​

💻 Code Idea: Function with Optional Parameter​

Loading Python environment...

Key Point: The parameter uppercase: bool = False means it's optional. If you don't provide it, Python uses False by default.

Functions Returning Multiple Values​

Pattern: When a function needs to return multiple pieces of information, return a tuple and unpack it.

💻 Code Idea: Return and Unpack Multiple Values​

Loading Python environment...

Why this pattern? Type hints make it clear you're returning three values. The unpacking line shows exactly what each return value represents.

Functions Checking Conditions — Predicates​

Pattern: Functions that return True or False are called predicates. They answer yes/no questions.

💻 Code Idea: Predicate Functions​

Loading Python environment...

Key Point: Boolean return types (-> bool) make it clear the function answers a yes/no question.

Functions Processing Collections​

💻 Code Idea: Function Working with Lists​

Loading Python environment...

Reading the Type Hint: scores: list[float] → input list of floats, -> list[float] → output list of floats.

Calling Functions — Using Return Values​

💻 Code Idea: Function Return Values Flow Through Code​

Loading Python environment...

Key Insight: Function return values are just data. You can pass them to another function, store them, or print them.

🚀 Specification Challenge​

Choose a real calculation you do regularly (convert temperature, calculate tip, check if someone qualifies for a discount). Write the function signature only (just def line through docstring, no body):

  1. What parameters do you need?
  2. What type should each parameter be?
  3. What type will you return?
  4. What will your docstring say?

Then tell your AI: "Here's my function signature. Generate the implementation." Compare what you expected vs. what AI generated. This teaches you how clarity of intent affects code generation.

✨ AI Tool Tip​

Your AI can generate function bodies from docstrings. The process:

  1. You write the specification (function signature + docstring)
  2. Your AI implements it ("Implement this function")
  3. You validate it works (Test with examples)

Better specifications → better AI output. This is how AI-native developers work.

Try With AI​

Learn function design through specification-first development with type hints and docstrings.

🔍 Explore Function Signatures:

"I need a function that validates user registration (email must contain @, username at least 3 chars). Design just the function signature with type hints and docstring—no implementation yet. Explain how the signature communicates intent."

🎯 Practice Refactoring to Functions:

"I have repetitive user validation code for 50 users in one script. Help me design 2-3 functions to eliminate duplication. Show me how type hints guide AI implementation, then validate [email protected] with username 'alice'."

🧪 Test Single Responsibility:

"Analyze this function: def process_user(email, username) that validates, registers, sends email, and logs. Critique it using single responsibility principle, then refactor into separate functions showing clear naming and focused responsibilities."

🚀 Apply Professional Function Design:

"Design a user authentication system with four functions: validate_password(), hash_password(), authenticate_user(), and create_session(). Write signatures with full type hints and docstrings ONLY, demonstrating how specification clarity makes implementation obvious."