In terms of working on a codebase daily, if thereās one thing that I wish Iād done sooner, and also wished that the engineers before and that still works with me, is to over-document everything.
By the statement above, I hope you can already understand what I am talking about. With complete documentation, you can easily find out what a function does, what it returns, what parameters it takes, and what it throws. Itās like a book that you can read and understand.
Some might even call it a ādocumentation-driven developmentā.
The challenges
But, I can see a few challenges that we might face in order to make it into a reality:
- Structure
Itās become a shamble if lengthy documentation doesnāt have any meaningful and understandable structure. If itās a novel, itās like you jump to a different act on each page. It doesnāt make sense at all.
For this, I personally really favouring the DiĆ”taxis framework. Itās built by developers and really puts developer needs in mind. But, it is still versatile enough to be suited to each team.
- Maintainability
Once you have put a lot of ācontentā in your docs, maintaining it and keeping up to date with the real system is a challenge. And no, if you think that making autogenerated documentation from the codebase is the solution, itās far from being sufficient (read here to dig more).
For this one, I can only think that habit and discipline are the only key. I might be wrong on this one, but thatās all I got for now.
Published on: