3 ms·

I agree on the content but disagree with the title. If you write tons of doctested documentation, that's a good thing? Imho, there is never enough documentati

• maccard 3y ago
  > Imho, there is never enough documentation. Even if it's outdated, it's still better than reading directly the source code and guessing everything from scratch. Hard disagree here. If the docs differ from the code, I'm left to figure out which is right. Too much documentation often leads to people writing pseudo code in English. We don't let you just copy and paste blocks of code into other blocks, why would we let you copy code into English? It's the exact same problem. Documentation should be expressing something you need to know about the code, not narrating it line by line.
  • Pannoniae 3y ago
    >"If the docs differ from the code, I'm left to figure out which is right." That's a good thing! It makes you think about what is actually the truth. If there was only code, you could easily get the wrong assumption silently. You wouldn't be confused, but you would also be wrong..... when the code and documentation doesn't match, you have to expend brainpower to figure out what's going on. This is a good thing, it also helps you learn:)
    • maccard 3y ago
      No, it means the person who made the change didn't do their job properly.