Is self-documenting code enough documentation? Do you comment your code, and if so, what are the rules you follow? Do you keep documentation outside your code, like requirements or design documentation, ADRs? Is this documentation valuable and why? How do you make sure the docs stay up to date?
Your approach to documentation
Publish Date: Feb 27 '21
1 2Comments 2 total
Nested SoftwareMar 3, 2021I generally avoid any detailed documentation inside of code (with the exception of library code meant for general consumption). I find it's better to use automated tests to explain what the code should do, and to let the code speak for itself with respect to design. In the few places where I feel a short comment may be warranted, I find it's often preferable to extract the code in question to a named function or variable instead. I do believe in properly documenting how to set things up - and to automate that as much as possible.
For our API, documenting each endpoint is necessary to generate the API reference.
We also keep a "developer wiki" which is a bit of external documentation and walkthroughs, tips, tutorials.
Design and requirement documents are usually archived on Google Drive, but from my experience they are only really useful in the beginning and are very high maintenance in case of changes, so we always keep them but warn future readers that things may have changed.