There are two types of design decisions we always seem to make while building large programs:
Architectural
Algorithmic
Architectural design decisions are decisions related to modularisation, division of responsibility, information accessibility and such things. For example, in a typical object oriented implementation, they would translate into decisions about class design, namespaces, fields and methods of a classes, inheritance hierarchy etc.
Algorithmic design is the choice of data-structure and control flow.
I feel, documenting architectural design decisions is best done offline, off code, in separate place. On the other hand algorithmic decision related documentation is best placed close to its implementation, as code comments.
Just an observation. Nothing biblical about it.
