Google Javadoc Standards ...

By -
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

Post a Comment

Popular posts from this blog

In ancapistan, if you have no property, you have no rights

By -
Ancaps often declare, "All rights are property rights." I was thinking about this the other day, in the context of running into libertarians online who insisted that libertarianism supports "the freedom of movement," and realized that this principle actually entails that people without property have no rights at all, let alone any right to "freedom of movement." Of course, immediately, any ancap readers still left here are going to say, "Wait a second! Everyone owns his own body! And so everyone at least has the right to not have his body interfered with." Well, that is true... except that in ancapistan, one has no right to any place to put that body, except if one owns property, or has the permission of at least one property owner to place that body on her land. So, if one is landless and penniless, one had sure better hope that there are kindly disposed property owners aligned in a corridor from wherever one happens to be to wherever the...
Read more

"Pre-Galilean" Foolishness

By -
 I am currently reading The Master and His Emissary , which appears to be an excellent book. ("Appears" because I don't know the neuroscience literature well enough to say for sure, yet.) But then on page 186 I find: "Asking cognition, however, to give a perspective on the relationship between cognition and affect is like asking astronomer in the pre-Galilean geocentric world, whether, in his opinion, the sun moves round the earth of the earth around the sun. To ask a question alone would be enough to label one as mad." OK, this is garbage. First of all, it should be pre-Copernican, not pre-Galilean. But much worse is that people have seriously been considering heliocentrism for many centuries before Copernicus. Aristarchus had proposed a heliocentric model in the 4th-century BC. It had generally been considered wrong, but not "mad." (And wrong for scientific reasons: Why, for instance, did we not observe stellar parallax?) And when Copernicus propose...
Read more

Against their will / we were taxing against their will / we were young and we were strong and we were taxing against their will

By -
Never one to allow a mistake to go uncompounded by a glaring error, Bob Murphy digs in deeper . He claims that "Taking money from people against their will is not akin to getting on the treadmill; it is akin to killing people against their will." Bob has introduced a largely irrelevant criterion here with his "against their will." Let us start with killing. (No, no, not killing Bob : we still love him despite his obstinacy.) The justice of a killing does not depend at all on whether the "victim" wants to be killed. If I shoot someone who is attempting to set off a nuclear weapon in Times Square, the fact that I killed him "against his will" does not make my killing immoral. And if a friend who is in despair asks me to shoot him in the head, the fact that he wants me to kill him would not make my action moral. Similarly, in taking money from people, the crucial question is whether you are taking it justly or unjustly, not whether they wan...
Read more