Don’t Lower the River; Fix the Bridge

An important rule 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 you are not clear

Change the code so it is clearer: improve the nomenclature; break operations into separate functions; or, if 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 explain 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

#codereview #cleancode

UPDATE: This also 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

 
0
Kudos
 
0
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 →