DHI / DHI/python-package-development
Add Ousterhout's comment philosophy to course content
- Ngôn ngữ chính
- Jupyter Notebook
- Star
- 8
- Fork
- 1
- Merge trung bình
- 4 phút
- Pull request đã merge (30 ngày)
- 1
Mô tả
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.
Hướng dẫn đóng góp
Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này
Hướng nghiên cứu
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.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- python
- Lĩnh vực
- content, documentation
- Loại issue
- Tài liệu
- Độ khó
- 3/5
- Thời gian dự kiến
- 1-2 ngày
- Mức độ hoạt động
- Đình trệ
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 48/100