DHI / DHI/python-package-development

Add Ousterhout's comment philosophy to course content

オープン
#34 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
主要言語
Jupyter Notebook
スター
8
フォーク
1
平均マージ
4分
マージ済み PR(30日)
1

説明

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.

コントリビューションガイド

このリポジトリのコントリビューションガイドは索引されていません

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。