Day 13: Function Design and Documentation

Learning Objectives

• AAP-3.D: Select appropriate libraries or existing code segments to use in creating new programs.
• AAP-3.E: For generating random values: Write expressions to generate possible values.

Essential Questions

• What makes a function well-designed and reusable?
• How does documentation help others understand and use our functions?

Materials Needed

• Presentation slides on function design principles and documentation
• Programming environment
• Documentation templates
• Function design rubric
• Peer review forms
• Exit ticket templates

Vocabulary

• Documentation
• Function signature
• Precondition
• Postcondition
• Interface
• Implementation
• Abstraction
• Specification
• Comment

Procedure (50 minutes)

Opening (8 minutes)

1. Review and Connection (3 minutes)

   • Review parameters and return values from previous lesson
   • Connect to today's focus on designing and documenting functions

2. Warm-up Activity (5 minutes)

   • Present an undocumented function with a cryptic name and parameters
   • Ask students to figure out what it does and how to use it
   • Discuss the challenges of using poorly documented functions

Main Activities (32 minutes)

3. Lecture: Function Design Principles and Documentation (12 minutes)

   • Explain principles of good function design:
     • Single responsibility (each function should do one thing well)
     • Appropriate level of abstraction
     • Clear interface with meaningful parameter names
     • Minimal side effects
     • Reasonable function size
   • Discuss the importance of function documentation:
     • Helps others understand how to use the function
     • Clarifies the function's purpose and behavior
     • Specifies preconditions and postconditions
     • Explains parameters and return values
     • Documents any side effects or exceptions
   • Introduce documentation formats:
     • Header comments
     • Parameter descriptions
     • Return value descriptions
     • Example usage
     • Inline comments for complex logic
   • Explain how good documentation supports abstraction

4. Demo: Writing Well-Documented Functions (8 minutes)

   • Walk through examples of well-documented functions
   • Show before-and-after examples of poorly vs. well-documented code
   • Demonstrate how to write clear function headers and comments
   • Show how documentation helps users understand the function interface
   • Illustrate how documentation can make complex functions accessible
   • Demonstrate how to document parameters, return values, and preconditions

5. Hands-on: Documenting Existing Functions (12 minutes)

   • Provide students with undocumented functions
   • Students add appropriate documentation:
     • Function purpose
     • Parameter descriptions
     • Return value descriptions
     • Example usage
     • Any preconditions or assumptions
   • Students may also improve function names and parameter names
   • Encourage students to think about the function from a user's perspective

Closing (10 minutes)

6. Activity: Peer Review of Function Documentation (5 minutes)

   • Students exchange their documented functions with a partner
   • Partners review the documentation and provide feedback:
     • Is the purpose clear?
     • Are parameters well-described?
     • Is the return value explained?
     • Could they use the function based on the documentation alone?
   • Students revise their documentation based on feedback

7. Exit Ticket and Preview (5 minutes)

   • Students create and properly document a function for a specific purpose
   • Preview that next class will focus on libraries and APIs

Assessment

• Formative: Quality of function documentation during hands-on activities
• Exit Ticket: Completeness and clarity of function documentation

Differentiation

For Advanced Students

• Challenge them to document more complex functions
• Introduce more formal documentation standards (e.g., JSDoc, Javadoc)
• Discuss documentation for edge cases and error handling

For Struggling Students

• Provide documentation templates with sections to fill in
• Focus on documenting simpler functions
• Offer examples of good documentation as reference

Homework/Extension

• Document functions from a previous assignment
• Research documentation standards in a programming language of interest
• Find examples of well-documented open-source code and analyze the documentation

Teacher Notes

• Emphasize that documentation is not an afterthought but an integral part of programming
• Watch for documentation that merely restates the code without adding value
• Make connections to professional software development practices
• Consider showing examples of real-world API documentation
• Remind students that they will need to document their code for the AP Create Performance Task