Writing improves thoughts and ideas. Doubly so for thoughts and ideas about code.
Writing, about software or otherwise, is a process wherein:
- thoughts and ideas are clarified
- ideas are transferred to colleagues
- culture (of a sort) is created by highlighting what’s essential and omitting what’s transient
Documenting code, as a form of writing, is a process wherein:
- the concepts and mechanics in the code are clarified
- what’s in our head today is made available to our teams (and ourselves) in the future
- culture happens by highlighting what’s intended and what’s “off the beaten path” when working with this codebase
I suspect that open source is (often) of higher quality than bespoke, proprietary software because it has to go through the crucible of documentation. Essentially, there’s a whole other design activity you have to go through when publishing a library or framework that internal/bespoke software does not.
I can’t objectively verify this. Subjectively, when I have made the time to write words about a bit of code I wrote, it has resulted in improving the design of the code along the way. Or, I better understand how I might design the code in the future.
Writing is a great tool for designing code. Use it more often!
