03 March 2014

Code doc: "Responsible for ..."

Instead of writing class documentation like:

/**
 * This class does X.
 */

Instead of that, please start writing class documentation like:

/**
 * Responsible for X.
 */

The difference seems subtle at first, however the latter is better because it sends you down the path of the Single Responsibility Principle as a default way of thinking about things.

If it's hard to write a sentence fragment "responsible for X" because X is really X, Y, and Z, then that is a code smell that can point to a need for more refined subdivision of responsibility.

No comments:

Post a Comment