Add Ousterhout's comment philosophy to course content
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 48/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- python
- Domain
- content, documentation
Research direction
Start by locating the course content for Module 2 and Module 6, then review how existing lessons present functions, modules, comments, and documentation. Done means the course explains the listed comment principles, includes the provided contrasting examples or equivalent examples, and adds the brief Module 6 callback if appropriate.
Written by the indexing model from the issue text.
Description
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.
- Dominant language
- Jupyter Notebook
- Stars
- 8
- Forks
- 1
- Avg merge
- 4m
- Merged PRs (30d)
- 1
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from DHI/python-package-development
-
Difficulty 2/5 1-2 days Newbie friendliness 88/100
-
Difficulty 2/5 1-2 days Newbie friendliness 72/100
DHI/python-package-development#37 · 1 comment ·
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
-
Difficulty 3/5 1-2 days Newbie friendliness 48/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 48/100
All issues in DHI/python-package-development
Similar issues
-
Add: hunch Open
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
AbdelStark/awesome-typesafe#104 ·
-
a11y admissions.uiowa.edu needs grooming SiteImprove best practice
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
AllTheMods/ATM-10-L#19 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 74/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100