Add Ousterhout's comment philosophy to course content
还没有人认领这个 Issue。
评估
- 难度
- 3/5
- 预计耗时
- 1-2 天
- 新手友好度
- 48/100
- Issue 类型
- 文档
- 描述清晰度
- 基本清楚
- 活跃度
- 停滞
- 技术栈
- python
- 领域
- content, documentation
调研方向
首先找到 Module 2 和 Module 6 的课程内容，然后查看现有课程如何介绍函数、模块、注释和文档。完成的标准是：课程解释列出的注释原则，包含所提供的对比示例或等效示例，并在适当的情况下添加简短的 Module 6 callback。
由索引模型根据 Issue 内容生成。
描述
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.
- 主要语言
- Jupyter Notebook
- 星标
- 8
- 派生
- 1
- PR 合并指标
- 30 天内没有已合并 PR
环境准备
这个项目没有提供开发容器、Dockerfile 或贡献指南，环境需要你自己搭建：先看它的 README，通用步骤见我们的新手贡献指南。
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
DHI/python-package-development 的其他 Issue
-
难度 2/5 1-2 天 新手友好度 88/100
-
难度 2/5 1-2 天 新手友好度 72/100
DHI/python-package-development#37 · 1 条评论 ·
-
难度 5/5 一周以上 新手友好度 35/100
-
难度 3/5 1-2 天 新手友好度 48/100
-
难度 2/5 1-3 小时 新手友好度 48/100
查看 DHI/python-package-development 的全部 Issue
相似的 Issue
-
New Internship未关闭new_internship
难度 1/5 1 小时以内 新手友好度 70/100
-
难度 2/5 1-3 小时 新手友好度 72/100
-
'outreach'未关闭new synset
难度 2/5 1-3 小时 新手友好度 70/100
globalwordnet/english-wordnet#1415 ·
-
难度 2/5 1-3 小时 新手友好度 72/100
521xueweihan/HelloGitHub#3832 ·
-
难度 1/5 1 小时以内 新手友好度 88/100