5 ms·

Documentation is like sex. If it is good, it is good. If it is bad it is good

nextlevelwizard 8y ago
Except when the documentation is out dated and has very little to do with the actual code. At that point you are better off without bad documentation than with it. I've wasted a lot of time solving strange bugs because the API had stayed the same as when the documentation was written, but the implications were totally different.
humbleMouse 8y ago
This is hilarious and 100 percent correct.
SketchySeaBeast 8y ago
But if the client wants me to pretend I care enough to do it well, they gotta pay.
fhood 8y ago
"Our code is self-documenting. If you need documentation then the code isn't written well enough" -Assholes who don't know what it is like to work with mature code bases.
- itsreallyme 8y ago
  "Our code is self-documenting. If you need documentation then the code isn't written well enough" -Assholes who don't know what it is like to work with mature code bases. - People who don't know how to write clean code
  - swagtricker 8y ago
    Sorry, parent poster: Gotta agree w/ above comment here. With the minor warning that the unit tests are included in this. In a good environment, I should be able to go to the tests to understand not only WHAT the code is doing but WHY it's doing it. No matter how 'mature' the code base is.
    - jakobegger 8y ago
      In any mature code, there is going to be unintuitive code that only exists to work around an external issue beyond your control. Recent example: when you authenticate to OpenSSH running on macOS 10.13 or 10.14, make sure to never attempt keyboard-interactive auth after password auth, or the server will stop responding. Somewhere you need to write this fact down, so that the next person who comes across your auth code doesn't change the order of authentication methods. You need to document things like that. If you have a mature code base, you'll have dozens, or hundreds of these workarounds for all kinds of issues. If you look at the code, it'll seem inefficient. If you don't document why the code looks like it does, then someone will come along (possibly you) a few years in the future and "optimise" that line. Sure, you could have a unit test that checks whether the workaround is in place. But then you STILL need to document why that unit test is there, or someone will come and consider it pointless and remove it.
  - devhead 8y ago
    or maybe they just didn't write the code? i mean, if it's mature it likely was a result of years of effort and many hands involved. some documentation is always better than none, lack of documentation is either laziness or dogma; neither of which is a valuable mindset when working on a team for a business.
  - discreteevent 8y ago
    I hope you are using someone else to judge how clean your code is. (Maybe you are, maybe it is). I have come across very little self documenting code outside of a textbook. Code is a very low level medium. In the meantime a comment can help save a lot of time.
  - Kuraj 8y ago
    Code is harder to read than write.
  - hinkley 8y ago
    I agreed with this until my current job, when it was stated cheerfully by a guy whose code is so shit lousy that I want to do violence to him (an emotion I haven’t felt in probably ten years). Management thinks he’s brilliant. Everybody else thinks he’s an insane asshole. Just because you know people who can say this with sincerity and gravitas doesn’t mean there aren’t assholes. There are always assholes.
    - kioleanu 8y ago
      I think the book _Pragmatic Programmer_ explains the concept of this asshole type of programmer and how to have the same results as him without being an asshole yourself
  - flatb 8y ago
    "Our code is self-documenting. If you need documentation then the code isn't written well enough" -Assholes who don't know what it is like to work with mature code bases. - People who don't know how to write clean code - People who think that not only they figured out what 'clean code' even means, but that everyone else will agree, thus single-handedly ending some 50+ years of heated industry-wide debate, numerous billion-dollar attempts by some of the most talented people in the world, and troves of 8-dimensional mental gymnastics about design patterns by way of a $21 ebook, a code review and some blog posts
    - fhood 8y ago
      Not to mention thinking that clean sensible code is always an option. There will always be something. It could be a kernel bug, it could be a quirk of an external library, it could be just to get the bloody thing to link against static libraries, but there will always eventually be an issue that requires a workaround that doesn't make sense without context.
Humdeee 8y ago
And it extends far beyond comments in source code. Don't be that person who people have to run to because he/she keeps everything in their head. It's not job security. Take some time and write things down for your future self and team members.
grstearns 8y ago
Documentation priority is inverse of volatility: 1) Why (requirements, decision points) 2) What (use cases, interactions, external APIs) 3) How (internal APIs) 4) Who (SMEs, owners, servers) And don't waste people's time; don't document things that are obvious.
quickthrower2 8y ago
I've heard the variant: If it is good, it's great. If it is bad, it is better than nothing.

Except when the documentation is out dated and has very little to do with the actual code. At that point you are better off without bad documentation than with it. I've wasted a lot of time solving strange bugs because the API had stayed the same as when the documentation was written, but the implications were totally different.

humbleMouse 8y ago

This is hilarious and 100 percent correct.

SketchySeaBeast 8y ago

But if the client wants me to pretend I care enough to do it well, they gotta pay.

fhood 8y ago

"Our code is self-documenting. If you need documentation then the code isn't written well enough" -Assholes who don't know what it is like to work with mature code bases.

itsreallyme 8y ago
"Our code is self-documenting. If you need documentation then the code isn't written well enough" -Assholes who don't know what it is like to work with mature code bases. - People who don't know how to write clean code
- swagtricker 8y ago
  Sorry, parent poster: Gotta agree w/ above comment here. With the minor warning that the unit tests are included in this. In a good environment, I should be able to go to the tests to understand not only WHAT the code is doing but WHY it's doing it. No matter how 'mature' the code base is.
  - jakobegger 8y ago
    In any mature code, there is going to be unintuitive code that only exists to work around an external issue beyond your control. Recent example: when you authenticate to OpenSSH running on macOS 10.13 or 10.14, make sure to never attempt keyboard-interactive auth after password auth, or the server will stop responding. Somewhere you need to write this fact down, so that the next person who comes across your auth code doesn't change the order of authentication methods. You need to document things like that. If you have a mature code base, you'll have dozens, or hundreds of these workarounds for all kinds of issues. If you look at the code, it'll seem inefficient. If you don't document why the code looks like it does, then someone will come along (possibly you) a few years in the future and "optimise" that line. Sure, you could have a unit test that checks whether the workaround is in place. But then you STILL need to document why that unit test is there, or someone will come and consider it pointless and remove it.
- devhead 8y ago
  or maybe they just didn't write the code? i mean, if it's mature it likely was a result of years of effort and many hands involved. some documentation is always better than none, lack of documentation is either laziness or dogma; neither of which is a valuable mindset when working on a team for a business.
- discreteevent 8y ago
  I hope you are using someone else to judge how clean your code is. (Maybe you are, maybe it is). I have come across very little self documenting code outside of a textbook. Code is a very low level medium. In the meantime a comment can help save a lot of time.
- Kuraj 8y ago
  Code is harder to read than write.
- hinkley 8y ago
  I agreed with this until my current job, when it was stated cheerfully by a guy whose code is so shit lousy that I want to do violence to him (an emotion I haven’t felt in probably ten years). Management thinks he’s brilliant. Everybody else thinks he’s an insane asshole. Just because you know people who can say this with sincerity and gravitas doesn’t mean there aren’t assholes. There are always assholes.
  - kioleanu 8y ago
    I think the book _Pragmatic Programmer_ explains the concept of this asshole type of programmer and how to have the same results as him without being an asshole yourself
- flatb 8y ago
  "Our code is self-documenting. If you need documentation then the code isn't written well enough" -Assholes who don't know what it is like to work with mature code bases. - People who don't know how to write clean code - People who think that not only they figured out what 'clean code' even means, but that everyone else will agree, thus single-handedly ending some 50+ years of heated industry-wide debate, numerous billion-dollar attempts by some of the most talented people in the world, and troves of 8-dimensional mental gymnastics about design patterns by way of a $21 ebook, a code review and some blog posts
  - fhood 8y ago
    Not to mention thinking that clean sensible code is always an option. There will always be something. It could be a kernel bug, it could be a quirk of an external library, it could be just to get the bloody thing to link against static libraries, but there will always eventually be an issue that requires a workaround that doesn't make sense without context.

Humdeee 8y ago

And it extends far beyond comments in source code. Don't be that person who people have to run to because he/she keeps everything in their head. It's not job security. Take some time and write things down for your future self and team members.

grstearns 8y ago

Documentation priority is inverse of volatility: 1) Why (requirements, decision points) 2) What (use cases, interactions, external APIs) 3) How (internal APIs) 4) Who (SMEs, owners, servers) And don't waste people's time; don't document things that are obvious.

quickthrower2 8y ago

I've heard the variant: If it is good, it's great. If it is bad, it is better than nothing.