Add Ousterhout's comment philosophy to course content

[ecomodeller]

Consider adding content about code comments based on Ousterhout's "A Philosophy of Software Design".

Key concepts to cover

• Comments as abstraction (describing what and why, not how)
• High-level vs. implementation comments
• Comments that reveal what code cannot express
• When to improve code clarity instead of adding comments

Example

# BAD: comment restates what the code does
def get_temperature(measurements):
 # Return None if list is empty
 if len(measurements) == 0:
 return None
 # Calculate the average temperature
 return sum(measurements) / len(measurements)


# GOOD: comment explains why (the business reason isn't obvious from code)
def get_temperature(measurements):
 # Sensors report -999 when disconnected; treat as missing data
 valid = [m for m in measurements if m > -900]
 if len(valid) == 0:
 return None
 return sum(valid) / len(valid)

The first example's comments add no value—the code is self-explanatory. The second example's comment reveals why we filter values below -900, which you cannot understand from the code alone.

Suggested placement

• Module 2 (Functions, classes, modules) - Core principles, taught early when students learn to write functions
• Module 6 (Documentation) - Brief callback distinguishing inline comments from API documentation

Module 2 is preferred since teaching good commenting habits early will improve code quality throughout the course.