How to document code?

Question

JavaScript

There is a big project that was developed for a long time by one person on js (coffescript + noda.js). It is necessary to make documentation so that other developers can work with the project. Where can I read what are the principles and approaches to writing documentation? Where to start, how to lead?

Answer 1

There are two extremes that are best avoided:
1. beautiful and comprehensive documentation requires huge resources to maintain
2. difficult to understand code, without the slightest clue where it all starts and ends
Standard solutions:
1. self-documenting code, written in such a way that the reader can understand what works for what and in what order.
2. description of interfaces (purpose of the method, type/essence of parameters, etc.) in the form of comments in the code.
3. automatic documentation (generated from comments) - effective only if the code itself is closed.
4. unit tests that fix the requirements for the code and demonstrate its use.
5. description of the high-level design (High Level Design, HLD), describing what elements exist, their relationship with each other and the main interaction scenarios.
Working documentation is a compromise of these practices that is relevant to the specific situation.
By the way, design work is not only documentation for the code, it is also a set of rules that will allow the architecture not to crawl into the woods for firewood, and also preserve the style of writing code for uniformity and easy code maintainability.