Class comments

We do use class comments to describe what a class is for, and sometimes how it works. We probably don’t do this often enough, and we probably don’t keep them as up to date as we should.

In my opinion, this argues for stronger focus on writing clear code, not just cracking down on class comments. A developer’s nature is to develop code, not to develop documentation. The best process is one that works with nature, not against it. (Tree-hugger theory of software development.)

Still ... for most classes a class comment can be quite useful. Please create them when you create new classes.


1997, 1998, Ronald E Jeffries
ronjeffries@acm.org
http://www.xprogramming.com