Make code better by writing about it

Writing improves thoughts and ideas. Doubly so for thoughts and ideas about code.

Writing, about software or otherwise, is a process wherein:

  1. thoughts and ideas are clarified
  2. ideas are transferred to colleagues
  3. 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:

  1. the concepts and mechanics in the code are clarified
  2. what’s in our head today is made available to our teams (and ourselves) in the future
  3. 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!