What is in a name?

I was about to submit my PR after having worked on it for an afternoon. The code I was writing was not too complex. I had spent more time investigating it than writing it and I was feeling good about myself.

I took one final look with my "code review" glasses on (aka. reading it like someone who would be reading this code for the first time) and I realize,  I have no idea what I am reading.

See, much like presentations, code can also be written to tell a story. It can tell your intentions (function names, variable names, comments) and your worries (test-cases and try catches). When I read my code, it did not pull the reader into my work. Rather, it told of obtuse content, such as TableAuditResult, which was misleading since it contained the raw material on which each auditor could make it's decision.

What followed that "almost PR" was 3 hours of refactoring and testing to reorganize the code so that a simpler story was told once the reader had found the entry point, which I helpfully pointed out in the PR message.

In the end, I submitted a change that would be easily readable, both to myself in 6 months when I had forgotten everything about this project, as well as to the poor intern who might have to update/upgrade/fix this code in a future where I have won the lottery and moved to the Bahamas. The PR went smoothly since people didn't have to constantly ask "what is this thing doing again?" and they found way more bug and provided more useful input because they could get their footing much more quickly.

Write your code with a story tellers mind. I don't mean it is the only thing worth worrying about. Rather, one of the most expensive things about writing code is the time people spend to maintain it and if you can make that journey cheaper and more pleasurable for you or someone else in the future, then you will have done a great job.