A reasonable approach to documenting code
Prioritize documenting the most valuable things to save time onboarding and ensure a more complete understanding of the developers that write it.
If you've been coding for any amount of time, I strongly recommend looking at your earliest work, and even from a few months ago. Chances are, you won't remember the details without takin some time to re-familiarize yourself with the problem you were solving and why you decided to go with the approach that you did.
A common saying I often hear is to write your code in a declarative way that you can understand without code comments. The argument is that comments quickly become stale and are unnecessarily verbose so most people skip over them anyways. And that comments are best used to explain "why" something is done. Especially when the thing you're doing lacks context, has gotchas or is a hacky solution. This usually works well and is accepted as a best practice.
In my experience, most people stop here and only document further if someone explicitly asks for it. While requirements change, it's a lot of work to write and maintain more documentation, and management likely won't care too much about this unless it's a public project, I think this core to the long-term success of a project. The time you save by skipping documentation will be soon be lost when you onboard a developer and have to spend much more time explaining things that you could have easily had written down.
A reasonable approach
This has worked well for me in the past and follows the 80/20 rule pretty well.
Application level
- A page on design decisions. Why did you choose X framework or approach over Y?
- A contribution guide. What is the process of setting this up for local development? How do you lint, format, run tests and deploy? What pre-requisites do you need to have for this app to run? How to commit changes? Where can I find the file that I need? Are there any conventions or rules that you need to follow?
UI
- A page on design. Who is the audience for this tool? What are you solving and not solving? What tenets are you basing decision off of?
- A readme for each reusable component. If a one-time use component, a JSDoc at the top is fine.
- JSDoc at the top of each module to explain what they do
Infrastructure and backend
- JSDoc at the top of each construct to explain what each piece does
- An architecture diagram. What services are being used and how do they connect to each other? Where does the data flow and what happens if an error occurs?
Other benefits
You'll gain a much more thorough understanding of how your system works as you write it down, trust me. It's hard to bullshit yourself when answering these prompts above and you may find that you don't know something as well as you should or should consider an alternative approach.
If it's a public project, you'll also make it easier to have other developers contribute.
Happy coding! SL
