We aim for self-documenting code. If there is a decision that absolutely can not be reflected in the code itself, a comment goes with the code as close to where the decision is implemented as possible.
We have a 10-year-old code base that is doing well and continues to support rapid, robust and maintainable development. The learning curve is higher than if the documentation were external to the code base and accurate diagrams existed, but unlike those artifacts the code will always be right about what the code is doing.
We have a 10-year-old code base that is doing well and continues to support rapid, robust and maintainable development. The learning curve is higher than if the documentation were external to the code base and accurate diagrams existed, but unlike those artifacts the code will always be right about what the code is doing.