So I'm at my first job after college, working on a mid/large frontend codebase. The initial codebase was created before I got here, and it had no testing or documentation. My teammate and I went in and created unit tests while adding requested features to the codebase. Our current feature request caused us to refactor a lot of the original code. Now I feel like we are at the point where we need to start adding documentation to the codebase. So far I have just been adding explanatory comments in front of functions in the codebase. But I feel like I have to do more.
Do you have tips or suggestions for code documentation? Any useful resources to learn more about code docs?
Top comments (10)
Writing proper documentation is an iterative process. We usually use the following pattern at IBM:
Preparation and Writing a first Draft
Comment your code extensively, explain especially public facing functions very detailed. Explain parameter and types.
Then wait some days, extract the comments and use the extracted comments to write documentation. Try to not look too much at the code during this step, in order to avoid getting lost in details.
Proof Reading
You can repeat the process until you find your documentation in a mature state. Dragging in more people ensures that the documentation not written in a way that is tailored to one specific reader. Each new pair of eyes gives you a new perspective on what is missing, wrong or difficult to understand.
I really appreciate this detailed explanation. I definitely don't want to fall into the trap of writing docs that are only understandable by me. So I will follow the steps for the first draft. Then I ask the person who will do our code review if they will be open to give us feedback on our docs also.
Just my two cents on comments (not necessarily helping you with how to document). Comments are a good thing, but only when used with discretion. I would resort to writing comments only when I think that my function is not able to convey its intents via its name, arguments and return type. Or when there are complex business logic that cannot be understood easily. Even in that case I would rely on my unit tests to serve as a documentation for my method.
I completely agree with you. The best documentation is the code itself, mostly without comments and good bunch of unit tests.
If you make any comments, they shouldn't be about the whats (the names should be clear enough to make such comments superfluous), but they should be about the whys, about intentions.
The first step is to decide what kind of documentation you need. Who is the audience? Will it be primarily used by developers (like yourself) who need to get familiar with the code base? Or is it geared towards users who just need to get things done and don't particularly care about the implementation. Both types of documentation are very important, but they are written very differently.
Once you have an audience in mind, start with an existing tool like Doxygen or ReadTheDocs or whatever tools are being used by codes similar to yours. Doxygen is particularly helpful for developer documentation because it can automatically create caller/callee diagrams for your code base. This is immediately useful to everyone on the team. With some skeleton documentation in place, work on getting buy-in from the rest of the development team.
Once everyone agrees that documentation is important, make it a part of the development cycle, not something that happens later. Require that pull requests for new features include the documentation. Or, enforce a commenting style that can be parsed by tool (e.g., Doxygen) and add this as a requirement. Every time someone refactors old code, they can add a small piece of documentation.
It's a slow process, but definitely worth the time! I highly recommend that a documentation piece become a requirement in all pull requests to help keep any existing documentation up-to-date.
Now that I think about it our audience is mainly other developers. We have a BA that does documentation for the user.
Right now I got the team to review our documentation during code reviews, which forces us to do it during major code changes. But you are right, it should be done more frequently (maybe every commit), so it doesn't feel so much like a burden. thanks!
I wrote an article on that topic: medium.freecodecamp.org/the-truth-...
Very good article.
Thank you, Maurice.
Show a lot of examples.