Comments

You must log in or register to comment.

Moonside wrote (edited )

"I don't write comments because comments and code drift apart."

"See the unit tests if you really want to figure out how it works."

"I'll document it later now that I got it working and it made it into the API."

"I'll lock down this method's name before writing its documentation."

"Contracts? Code is law."

"We use test driven development here so we don't need dedicated testers."

"The language I use doesn't support checking class invariants well so I just ignore them."

"It was clear enough for Torvalds."

"Commit it now, compile it later."

"I don't write documentation for functions besides types, since types are compiler verified and they are plenty good anyway. Everybody gets these things just like me."

5

twovests OP wrote

tbh I didn't know about 'class invariants' until just now, but Wow these all Hurt to Read

1

Moonside wrote (edited )

If I was an instructor on some software course, I'd make an online assignment to come up with 5 excuses for not writing documentation and share the best answers with the class afterwards.

Class invariants are imo cool and underappreciated part of OOP. It's also my belief, untainted by any real research though, that designing, verifying and testing them would kill lots of bugs.

2

musou wrote

"comments are bad" is a surprisingly common opinion in the industry and also one of my least favorites

3

Moonside wrote

It has this cute logic of "excess comments indicate poor quality" and also this hidden thing where you don't need to write comments that you find boring to write anyway but now you have a virtuous reason not to.

2

musou wrote

that's exactly the common attitude i hate so much and it drives me batty. to me, a lot of comments indicates a lot of complexity, not necessarily bad quality. sometimes the things you have to do are just complicated! and it doesn't mean the code is bad, just that you're doing something hard. and if you don't write a ton of comments about it then when you have to understand it again in six months it's gonna be just as hard, and take just as long, as arriving at the solution the first time.

i'd rather just take the risk of comments getting out of sync with the code they decorate, because at that point they'll be about as useful as no comments, and then you've only wasted whatever span of time it took you to write them, and i think most everybody can write comments faster than they can write code.

1

Moonside wrote

I feel like this is, again, some Uncle Bob bullshit. Seriously, fuck that sexist prick. He has this schtick about how TDD is all and other techniques to improve reliability and reduce errors are bullshit. Like I would be much more congenial to the attitude if it implied things like (choose your own picks):

  1. programming by contract
  2. property based testing
  3. fuzzers
  4. unit testing
  5. integration testing
  6. good method documentation, perhaps with (an) example(s)
  7. literate programming
  8. code review
  9. formal specs
  10. some nicer type system
  11. pair programming
  12. safer languages - if there are no segfaults, you don't need to advertise the risk of one
  13. Have some people dedicated on hammering your software in evil manners
  14. proofs (but that's avant garde tbh)
  15. stats on commits/bugs per product, project, package, module, file, method/function. If something gets a lot of work done, unleash the testers.
  16. Outsourcing to Donald Knuth

I think it's the case usually that this comment hater has one or three favorite techniques they like and thus disregard the rest of the universe and I bet they don't even have TAOCP on their book shelf.

2

musou wrote

this!! holy shit this.

and it's funny that you mention the knuth books because reading knuth is what got me into literate programming tools that would send comment hater types into apoplexy.

1

Moonside wrote

I've read some of TeX book and a little bit of Knuth's journal articles, but face the facts, dude rules and when it seems like he's wrong (like with goto), he always had something interesting to say about it.

3