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!

Fair's fair!

More college diversity and tolerance