Notes

Writing Code for Humans to Read

Tips and notes on writing code that is easy to read and pleasant to look at

Edit on GitHub

Programming
3 minutes

Programs are meant to be read by humans and only incidentally for computers to execute. - Donald Knuth

  • Write your code for humans, humans are the ones who’ll read, maintain and improve it. Computers only get machine code, don’t worry about it.
  • Whitespace is amazing when done right
  • Be consistent. Be consistent in your naming, in capitalization, in spacing, in indentation, in code style. Pick a style, and stick to it.
  • Have a directory based README file, but only if it is necessary. Don’t make a directory just for a README file, that’s over-organizing it.
  • Documentation to the code should live with the code (i.e. comments). Ideally, your code should be self-documented
  • Don’t comment how (unless it’s really complicated), focus on the why
  • Abstraction can make things hard to understand, proceed with caution

You only write it once, you’ll read it lots of times

  • Don’t add tongue twisters in your code
 1// e.g.
 2
 3class UrlFetcher {
 4  public static function fetchUrl() {
 5    // ...
 6  }
 7}
 8
 9$response = UrlFetcher::fetchUrl($url); // read this out loud. 
10
11// remember, some people subvocalize what they read..
  • Write your code for this application, not for future applications. You’ll write new code in future because you’ll be smarter.

If statements

  • Always return what you’re expecting last. Do the checks you need first and then don’t nest any of the return values that you want to output
  • Keep your intended return statement out of the if blocks.
  • By keeping the inteneded return statement out of the if blocks, you’ll avoid code duplication. If the return statement is in the if blocks, you’re probably repeating it inside the many if blocks for every successful check
  • By keeping the expected return statement at last, you can do as many checks as you want returning null/ throw exceptions etc. before the return statement
  • Checking things that are negative might just be a better approach. Check for negatives and error out, instead of checking for positives and returning every time
 1// Don't do it like this
 2<?php
 3
 4class User {
 5  public function fullName() {
 6    
 7    if ($this->firstName && $this->lastName) {
 8      return $this->firstName . ' ' . $this->lastName;
 9    }
10    
11    return null; // return null by default
12  }
13}

 1// Do it like this, this is better
 2<?php
 3
 4class User {
 5  public function fullName() {
 6    
 7    if (!$this->firstName || !$this->lastName) {
 8      return null; //return null if the firstName or lastName don't exist
 9    }
10    
11    return $this->firstName . ' ' . $this->lastName;
12  }
13}

Writing un-nested code

Here’s and example of code where you’re uploading a file

 1// This is MEH
 2// You have to keep a mental model of states (if inside of if and then that else)
 3<?php
 4
 5if (isset($_POST['file'])) {
 6
 7  if (in_array($fileExtension, $allowedExtensions)) {
 8  	// Upload file
 9  } else {
10    return;
11    // Error and redirect
12  }
13  
14} else {
15  return; 
16  // Error and redirect
17}

 1// This is BETTER 
 2// Do the negatives first (cleaner, easier to read, easier to maintain)
 3<?php
 4
 5if (!isset($_POST['file'])) {
 6  return;
 7  // Error and redirect
 8}
 9
10if (!in_array($fileExtension, $allowedExtensions)) {
11    return;
12    // Error and redirect
13} 
14  
15// Upload the file!
Browse all topics