2 ms·

I agree with this, but have had trouble getting support for the idea of focusing on documentation among my coworkers. The major concern is that comments can rot

I agree with this, but have had trouble getting support for the idea of focusing on documentation among my coworkers. The major concern is that comments can rot as code changes and the comments/documentation are not updated to reflect the changes. It's my opinion that it should just be part of the developer's discipline to update documentation as they update code, but this seems not to be practical when not everyone shares my idealism for documentation. What ways are there to get buy in from those that need to be convinced about the value of documentation?

buster 14y ago
I can feel your pain.. Maybe you can convince them to update atleast the docstrings and use some documentation generation tool? That's mostly only API docs but still... it's near the code that is touched and should be just on the screen while changing code :)
meaty 14y ago
Documentation is part of engineering. Hire engineers rather than two bit coders. They already have the culture burned in. Works for us. Most people not up to it I.e. find it boring or can't put a sentence together bail in a month because they can't get their code through the review cycle. They are made well aware of the requirements at interview time. We're in financial sector so sound engineering and documentation stops us getting in deep shit. Case in point recently, one of our service providers broke their service API silently. We had their documentation, contracts etc set in stone in source control, named and dated as were our integration paths. When they pointed the finger at us, we were covered. The small detail was recorded (1 penny rounding method) which meant we could trace it instantly, pop open our log4j dumps and found that they sent the value wrong. Not only that, we raised it to start with because our constraints were documented and assertions were in place.
powatom 14y ago
Documentation should most certainly be updated as the code changes. Programmers should realise that the documentation is just as important (if not more so) than the code itself. If people don't know how to use your wonderful API, then it's useless. If your comments don't accurately reflect the current code, then either the comments are wrong, or your code is: it's dangerous to have outdated comments in the code - somebody may come along, read the comments, and 'correct' the code because the code didn't do what the comments described it as doing.
dexen 14y ago
A man with one watch knows what time it is. A man with two watches is never quite sure. Documentation and code can, and surely will, diverge from one another, leading to all kinds of nasty misunderstanding. As long as there aren't any reasonable† tools for keeping them in sync, it's best to avoid the problem altogether. IMHO it's good practice to have separate `implementation' (mostly code and static data) and `businesse requirements' (mostly documentation). Minimize overlap, strive for singular responsibility: it should be clear whether a particular change should go into documentation (change in requirements) or into implementation (to match the requirements). Tangentially related, if you have a habit of using `git blame' (or equivalent in your SCM), commit comments are good place to mention changes in business requirements, especially small ones. † nope, UML is not an aid here.

buster 14y ago

I can feel your pain.. Maybe you can convince them to update atleast the docstrings and use some documentation generation tool? That's mostly only API docs but still... it's near the code that is touched and should be just on the screen while changing code :)

meaty 14y ago

Documentation is part of engineering. Hire engineers rather than two bit coders. They already have the culture burned in. Works for us. Most people not up to it I.e. find it boring or can't put a sentence together bail in a month because they can't get their code through the review cycle. They are made well aware of the requirements at interview time. We're in financial sector so sound engineering and documentation stops us getting in deep shit. Case in point recently, one of our service providers broke their service API silently. We had their documentation, contracts etc set in stone in source control, named and dated as were our integration paths. When they pointed the finger at us, we were covered. The small detail was recorded (1 penny rounding method) which meant we could trace it instantly, pop open our log4j dumps and found that they sent the value wrong. Not only that, we raised it to start with because our constraints were documented and assertions were in place.

powatom 14y ago

Documentation should most certainly be updated as the code changes. Programmers should realise that the documentation is just as important (if not more so) than the code itself. If people don't know how to use your wonderful API, then it's useless. If your comments don't accurately reflect the current code, then either the comments are wrong, or your code is: it's dangerous to have outdated comments in the code - somebody may come along, read the comments, and 'correct' the code because the code didn't do what the comments described it as doing.

dexen 14y ago

A man with one watch knows what time it is. A man with two watches is never quite sure. Documentation and code can, and surely will, diverge from one another, leading to all kinds of nasty misunderstanding. As long as there aren't any reasonable† tools for keeping them in sync, it's best to avoid the problem altogether. IMHO it's good practice to have separate `implementation' (mostly code and static data) and `businesse requirements' (mostly documentation). Minimize overlap, strive for singular responsibility: it should be clear whether a particular change should go into documentation (change in requirements) or into implementation (to match the requirements). Tangentially related, if you have a habit of using `git blame' (or equivalent in your SCM), commit comments are good place to mention changes in business requirements, especially small ones. † nope, UML is not an aid here.