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.
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.