Don’t Mansplain Your Code

When getting one’s code or wiki entry or blog post reviewed, if a reviewer asks a good question (e.g. what the code is doing or why the code does not follow the common conventions), don’t answer them directly The problem is not that they have a question; the problem is that your code or text is not clear

Don’t mansplain with comments, READMEs, or call-outs in documentation; improve it so it can clearly speak for itself. A comment can improve code if it explains why the code is not doing the obvious thing; otherwise, it is compensating for something that can, with improvement, will not need compensation

Comment only what the code cannot say – Kevlin Henney

Change the text or code so it is clearer: improve the nomenclature or break operations into separate functions; add a diagram to show what you mean. You will likely find bugs, missing cases, or other improvements while refactoring your work. In any case, your code must be able to speak for itself unless you add your personal phone number for late-night calls

Don’t write so that you can be understood; write so that you cannot be misunderstood – William Taft

First appeared on LinkedIn 10 Jan 2020

Second appeared under Don’t Lower the River; Fix the Bridge

 
1
Kudos
 
1
Kudos

Now read this

The Tragedy of Heroes

In times of crisis, everyone just gets stuff done to keep the boat afloat and ship that one, promised feature. Young startups are constantly in crisis: pivoting, shucking and jiving, all hands on deck, working all night to get the demo... Continue →