Computer Science 203:

Software Engineering

Gregory M. Kapfhammer

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

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

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?

Write the comments first

Write the tests first!

Tests are executable documentation

Let's improve some comments!