every line of code should be commented
Easy. 10 lines, no comments. After writing a couple of million lines of code, the more code I write, the more I unwind it. Somewhere along the line, adolescent programmers got the idea that jamming all your logic into as few unreadable lines as possible is the fastest way to manliness. Way, way wrong.
True, very true indeed. Squeezing as much as possible into single line creates 100% surely maintenance problems, since those single liners must be first completely unwind, before changes can be actually done.
In java, this ”everything in single line” poses itself usually as ”final” variables, which are initialized with deeply nested ”?:” blocks.
As side note, please notice that this actually creates also actually slower compiled code, since those ”?:” constructs are just inline form of ”if-else”, but with restriction that ”else” branch cannot be left away; thus more code is actually generated (with lowered readability).
Then question remains how to comment java code intelligently without extra overhead.
Well, answer is very simple: Comment rarely, API spec (== javadoc) ”always”. I.e. scattering low level comments is bad, since they usually tend to repeat actual code lines. And javadoc needs to answer basic W+ (why, what, …). Point is that, something which is not specified, is by definition broken.
Comments are, however, required occasionally to clarify possibly slightly obscure code. For example, reference to some external source for algorithm, ”// HACK Why this instead of clean solution”, reference to bug tracking system (if fix is obscure, and thus there is danger that someone can remove/move single line fix since line seems to be reduntant/incorrectly placed) and such.
Of course javadoc is not required blindly. Defining simple default values for entries, and using good naming of methods and parameters allows leaving reduntant javadoc away in lot of cases (default values, and good names describe everything relevant).
For example, default rules for API spec
1) null parameters must be documented (WHAT is done if parameter is null)
* i.e. parameters are always non-null, unless something else is specified
2) null return value must be documented (WHY return value is null)
* i.e. return value is always non-null, unless something else is specified
3) …
These simple project wide default rules immediately means that javadoc can be left away for all cases where parameter or return value is non-null (which tends to be case in java). This immediately means that anyone using API can simply code according to API spec, without concerning possibility of null values (ex. default is that return value is non-null), which immediately increases code readability and reliability.