[personal opinion incoming] It depends what sort of code you are writing. Documentation can tell you -> What a piece of code does => Properly written code can

[personal opinion incoming] It depends what sort of code you are writing. Documentation can tell you -> What a piece of code does => Properly written code can be self sufficient in that if the domain is not too complicated. -- Why a piece of code exist => Git history and commits linking to user stories can also serve that purpose, to an extent. -- How the code is architectured, best practices etc. => I don't think there is an equivalent for that just using code. In my own opinion (front end dev) I would: - leave comments in the code only if it's doing something unexpected, because of a weird edge case, i.e some sort of hack - Create documentation on the overall architecture of the code. Keep that up to date if new pattern emerge. - Create documentation on specific area of the code, if they are complexe enough. "How we handle this feature" sort of stuff. And I would keep it at that. That is for a product. If you work on a library / framework (even internally), then you want a full API documentation. Backend has different requirements.