Don’t Mansplain Your Code

When getting one’s code reviewed, if a reviewer asks what the code is doing or why the code does not follow the common conventions, don’t answer them The problem is not that they don’t understand; the problem is that your code is not clear

Don’t mansplain code with comments, READMEs, or call-outs in documentation; let it speak for itself

Change the code so it is clearer: improve the nomenclature; break operations into separate functions; or, if absolutely necessary, add a comment. You might find bugs, missing cases, or other improvements in clarifying the code. In any case, your code must be able to speak for itself unless you add your personal phone number

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

Comment only what the code cannot say – Kevlin Henney

This principle includes comments on a Wiki (e.g. Confluence). Don’t reply to the comment; edit the entry so it answers the question

First appeared on LinkedIn 10 Jan 2020

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


Now read this

Four Unintuitive, Critical Things to Learn About SketchUp

1. It Really Wants To Be Modal # click-release-move instead of click-drag1 The common click-drag idiom used everywhere else does not work well in SketchUp Once you are in a mode (by selecting a tool and clicking on a starting point... Continue →