If you write tons of doctested documentation, that's a good thing?
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.
If you write tons of doctested documentation, that's a good thing?
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.
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:)