Color Scheme
Key Concept
Corresponding Diagram
In-Class Discussion
In-Class Activity
Details in the Textbook
Philosophy of Software Design
Chapters 12 through 15
Comment Excuses
Good code is self-documenting
I don't have time to write comments
Out-of-date comments are misleading
Comments are worthless!
What does source code not express well?
Comments should capture intentions of the designer
Good comments improve system design
Good comments reduce complexity
How to ensure good comments?
Application to the software project
Comment Goals
Pick conventions
Don't repeat the code
Add precision with low-level comments
Enhance intuition with high-level comments
Say what and why, but not how
Cross-module design decisions
Application to the software project
Naming Conventions
Bad names cause bugs
Paint a word picture
Pick precise names
Use names consistently
Long names? Short names? Trade-offs?
Tests are executable documentation
Let's improve some comments!