DHI / DHI/python-package-development
Add Ousterhout's comment philosophy to course content
- Vorherrschende Sprache
- Jupyter Notebook
- Sterne
- 8
- Forks
- 1
- Ø Merge
- 4 Min.
- Gemergte PRs (30 T.)
- 1
Beschreibung
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
```python
# 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.
Beitragsleitfaden
Für dieses Repository ist kein Beitragsleitfaden indexiert
Bewertung
Dieses Issue wurde noch nicht bewertet.