Google Javadoc Standards ...

The Google style guide for Java requires every class and class member to be described by a sentence fragment.

I think there is some wisdom in this. Methods/classes/attributes in programs are hardly islands to themselves. They at least modify *something* about the computer. And usually more: creation and modification of objects, threads, messages, data. All these will be propagated throughout the whole system. And side-effects can be difficult to predict.

In this way code is itself a sentence fragment. Why not be honest and leave your documentation as something incomplete in itself?

Comments

Popular posts from this blog

Central Planning Works!

Availability bias