Readable Code: Name Everything

Consider the following code samples.

// Specimen A 

if ($forceClose !== ' ' && $forceClose !== NULL && $issues['forcedClose'] && $forceClose > 0) 
     $this->saveAttrForUser($user, 'forced_close', $forceClose);
     if ($forceClose == '1') 
         Log::saveWrite("App killed");
// Specimen B
// note the prefix 'b' indicates type Boolean, the prefix 's' indicates type String
$bGotValidMessageFromClient = !($sForceClose !== ' ' && $sForceClose !== NULL);
$bAppPassedExitMessage = $aIssues['forcedClose']; 
$bExitWasForceful = ( (int)$sForceClose > 0);
$bAppWasForceClosed = $bExitWasForceful && $bGotValidMessageFromClient && $bAppPassedExistMessage;

if ($bAppWasForceClosed) 
     // A comment here that would mean something...
     $this->saveAttrForUser($sUserId, 'forced_close', $sForceClose);
     $bForceCloseWasAKill = ($sForceClose == '1');
     if ($bForceCloseWasAKill) 
         Log::saveWrite("App killed");
These two samples contain the exact same logic. The former is more direct, essentially it inlines all of the variables in the latter. And that is why it is worse. A variable serves as a unit of abstraction, and a well-named variable is a comment; thus having more variables is better. In fact, all if conditions should the form if ($bSomeVariable) {, that is, never put a complex expression within the parentheses of the if. If the logic is particularly complex then use multiple variables, as seen in the sample above.

All if conditions should the form if ($bSomeVariable) {

At first glance, the bottom example is longer and may look intimidating. But it is superior because it exposes its internal logic. Try deciding what the top code does, and what ‘1’ indicates in that code. Then consider the bottom code. The top is an actual code sample.

And while we’re adding in these extra variables, let’s name our variables clearly. Programmers seem to have some unspoken assumption that variable names need to be less than 10 characters and not have prepositions… Maybe this made sense when you had an 80 character wide monochromatic screen with no form of autocomplete, but technology has made that trend obsolete.  I suspect most people would try to turn the variable name $sLinkToUniversalDownloadPage into something like $sUniversalDownloadLink which is inferior because it is ambiguous (is the link universal or the download universal?).

Or, for example, what would a function named “OpenFileLock” do? Is it opening a lock on a file? Is it filing a lock (in some kind of lock registry)? Is it locking an open file? Each of the three words in the title can be read as a multiple parts of speech (i.e. verb, noun, adjective, etc). Or perhaps FileLock is an existing class in this codebase. Prepositions here would make all of the difference.

Name everything; name it well.

Death By Metrics

‘A little knowledge is a dangerous thing’ – Alexander Pope


TL;DR – Graphs, dashboards, and metrics give a psychological illusion of control and understanding which is usually false and can be worse than no information at all.

Why is it so easy to fall subject to crappy metrics? Let’s consider a story. You’re a project manager and you just got yelled at because the engineering project you manage is already 2 sprints behind. You feel helpless. You asks the engineers why everything is taking longer and they give technical explanations about unknowns that you can’t see at all. You really don’t know anything.

Then something magical happens: you discover you can look at the engineers’ pull requests, and see how many PRs they make each day and how many diffs are in them. You start to look at these and start to notice patterns. Maybe less PRs get done on work from home Mondays… are they slacking off? When all you have is a nail, everything looks like a hammer.

And you just ruined the company. Suddenly you’re wondering why Bob has the fewest commits, why there are fewer PRs on work-from-home Mondays, why there has been a decrease in number of PRs last month. The answers respectively are: Bob is the only one to comment  his code so everybody except him is sped up because of it, sprints start on Mondays and fewer PRs have 1 day turn-around so this biases your results. Everything your one tool might lead you to assume has been entirely incorrect.

Or worse, you decide to evaluate engineers based on their Jira tickets. You have engineers estimate their tickets and then see if they can meet their goals on time. Suddenly you have incentivized your engineers to overestimate tickets, play “hot potato” with responsibilities (“Not really a bug! Ticket Closed!”), not help each other (teaching time just makes you look slower), and not invest in long-term architectural improvements that won’t show immediate benefits.

Or you judge the success of a UI change based on a funnel. In an attempt to get the best open-rate for your marketing email you have somebody come up with various subject lines and pick whichever has the highest open-rate. This is an A/B test. Suddenly you’re sending out emails with link-bait titles like “See what your friend posted about you,” that get a high open-rate but immediately get deleted for being deceitful once opened. Or your new button placement gets tons of clicks because it’s too close to the scrollbar.

Or worse yet, you decide to judge the success of your company based on Monthly Active Users. 
You have your awesome facebook game and have 30 million MAUs. You force all of your users to send out invites to all of their friends and Viola 31 million MAUs! You change your code so that every one of your users must send invites to friends every week. Now you have 32 MAUs. The graphs look pretty convincing, you get promoted. And you wrecked the company. A year later facebook changes the rights to your app so that you can’t spam its users, your users have been pressured by their friends to stop spamming invites, your entire company has become a laughing stock in the gaming industry and is now lampooned everywhere for the rest of its existence.

The common pattern here is  individuals trying to substitute a simplistic chart in place of deep industry experience. It is people with finance degrees changing videogame experiences, MBAs insisting on multiple A/B tests to change an icon, or a non-technical hiring manager not calling a Bill Gates for an interview because he doesn’t have a CS degree.