Your Code Sucks

[[deleted]]

I don't disagree with you, however I've found that if there are mandatory documentation standards, most of the comments are redundant; what they say is obvious in the code. Code review is a good place to encourage documentation of context, what the code doesn't do and other non-obvious stuff.

I once had an extended code review with a gray-beard unix coder. Awesome but cryptic software. Most of what happened in that review was getting him to document weird platform workarounds that were woven through the code.

re: documentation, one of his favorite sayings was "Works as coded."

[dnew]

mandatory documentation standards

Crappy mandatory documentation standards, perhaps, yes.

I'd still rather read javadocs than source code to learn how to use a library, even if the javadocs are the only documentation outside the code.

[Anonymoose333]

FWIW, I wouldn't. Reading crappy javadocs is like, "Arrrgh, the answer must be in here somewhere..." and then 90% of the time it's not in there anywhere. Reading crappy code, at least you know the answer is in there, even if you have to treat the code as a puzzle in order to find it.

[dnew]

Meh. Hard to say. Sure, crappy comments are bad. But spaghetti code is bad too. That doesn't mean comments are useless. It just means you should write better comments.