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