Documentation should be in the comments. Not in a separate document, because it will get out of date.
The most important comments give the big picture. They describe the “why”, the overall structure and design choices.
Where do we comment?
- Top of the file
- Class/structure definitions
- Understanding the data means we can understand the program
- Declaration of functions (how to call, what it does)
- Tricky code (but try to rewrite for clarity first)
Do not leave commented out code in your project, since Git has all the code history. Do not translate clear code to English (it’s unnecessary!).