Comment by Alexandervn

The problem is that the implementation of the 'why' can be scattered over many files, classes, functions, etc. So where to put the comments?

In my projects (usually building websites or webapps) I therefore add a 'readme.md' to the root of the project and document general choices there.