The Professional Web Codebase

One of the major advantages of the high career mobility in SF … Cross pollination. Yet each new codebase I comes to seems to lack a few of the following. So I figured I’d list out the essentials that every web codebase should have.

  1. The Obvious: Git, IDE, MV*, relational DB, 3 environments that match production.
  2. Language regularization:Each language has its own idiosyncrasies. Learn your languages weakness and make helper functions to accommodate. In PHP, these weaknesses include single-threaded, bad undefined index default behavior.My preferred solution to PHP’s single-threaded limitations is to make use of a job queue. This will emulate additional threads for heavy tasks (e.g. sending emails to all of your user base) or high-latency tasks that ideally should be asynchronous (e.g. certain API calls). I’ve seen this done well, and I’ve seen it done poorly. From experience, I’d point out the following lessons: don’t use a message queue as a job queue and the DB is a great place to store a home-grown job queue [because it provides great visibility, resilience, can be controlled programatically, can be exported to disk, is atomic, etc].

    In PHP, out-of-bound reads on arrays return null and log a notification to the event log. As this is never the engineer’s intent, I always write two helper functions. One that looks up an key and returns a specific value if the key isn’t found (for cases where you’re using the array as a set). The other function looks up the key and returns an exception if the key is not found (for normal cases where the key should always be present).

    I strongly believe once you handle these edge cases most popular languages are pretty interchangeable (javascript, java, php, python, ruby).

  3. A powerful, generic staging environmentOne of the most impressive and useful technologies I saw was something we called humblebrag. It was a script that caught all requests to *…. It then took the *, checked-out the corresponding git branch, and mapped the request to that particular branch. Thus in effect, we had a zero-effort way to have all branches usable simultaneously on a single server, even by non-engineers.Doing this can be a little harder in more complex environments with versioned services listening on ports, if you don’t plan for it early.
  4. A circuit breaker. Download one from github.
  5. An ability to do cross-server mutexes.
  6. A simple, generic read-through-caching function.
  7. A powerful logging system connected to an alerting system
  8. An A/B test system. Even if you’re not doing A/B tests on user-experience, it can be a great way to rollout to a small portion of users or internal-testers to ensure stability on a new environment.



Thoughts on the equation of automated testing

Like any other principle, types of testing justify their existence in the time they save you. That is, presuming that software quality is ensured by manual testing in the absence of automated testing, the criteria for telling if adding a test is appropriate is whether the time taken to write the test is less than the expected time saved by the test.

I want to touch on the notion of testing everything. Aside from being inefficient, I’m confident it’s not realistically possible. That is: I’d wager that for any real, used codebase with a set of tests one can write an alteration that will break the codebase while keeping all the tests passing.

If you accept the conclusion that testing everything isn’t plausible (and no, 100% code coverage certainly isn’t testing everything), then the question becomes when/where do we test? Well, obviously in cases when the time saved exceeds the time spent implementing the tests. But let’s break this formula down a little. What factors influence the time saved and inform the decision of which things to test?

  1. The probability that code will break (and the number of times)
  2. The difficulty of manual testing
  3. The probability that the test will catch the code breaking

This is a start, let’s break it down further:

  1. The probability that code will break (and the number of times)
    • Amount of change to be made to code
    • Difficulty of code
    • Team Size (i.e. people working on code who don’t understand it)
    • Intensity of external factors/dependencies (environments)
  2. The difficulty of manual testing
    • The variety of different cases in the piece of code (“branchiness”)
    • The visibility of a problem when present
  3. The probability that the test will catch the code breaking

Based on this list, a hypothetical case where implementing a unit test might be the most valuable:  You have a complicated algorithm that uses advanced mathematics you don’t entirely understand which you will need to optimize several times for speed. Moreover, other team members will be working on it too. It relies on special GPU processing which has varying logic for different hardware. It also has branching logic that requires at least 8 test cases to ensure accuracy. Because the math is so complex, determining if the function has answered correctly requires looking at every digit of a 15 digit number.

A hypothetical case where implementing a unit test might be the least valuable:  You are putting one line of code into your app’s startup to set the background color to steel-grey. It’s a basic 1-liner. Nobody else will touch your code, and you know for a fact from your waterfall documentation that this requirement will never be altered. Your app only runs on a very specific device on one OS. There is no special logic involved. Every time you startup your app (which takes .01 seconds) you’ll immediately notice whether or not the background color is right. 

I believe an expert engineer will always be doing this math with all code he writes, while keeping in mind a margin of error in his estimations. And I think any engineer who opts for a simpler equation is being simplistic and in that respect, the less advanced engineer.

The [limited] Role of Principles

A programming principle should only be followed when it provides more long-term benefit than any alternative. This may seem self-evident; it should be apparent from the fact that a principle that doesn’t provide long-term benefit obviously isn’t a good principle.

This is something that mediocre problem-solvers don’t always understand: deviation from generally accepted principle can be a sign of weakness or, contrarily, a sign of strength.

To take an analogy, in chess it is said that a rook is worth five, a bishop three, and a pawn one and so on. These facts aren’t anywhere in the rules of chess, they are just very good approximations, overall, that emerge from the game. About 90% of the time, you can use math based on these numbers to make good decisions.

However, 10% of the time other situation factors supersede this principle. Though there is an appeal to such simplicity, as one becomes closer to a master of chess he must let go of these numbers and move to a more advanced situation calculus. The same applies to coding.

Even the purest of coding principles have exceptions: though you’ve probably never considered it, every time you copy-paste you participate in a violation of DRY.

I’d like to reiterate, every single (non-trivial) coding principle necessarily has an exception. Why? Because every principle incurs a cost of a situation benefit. And for any such principle we can imagine a scenario, however unlikely, where the situationality of that benefit is totally avoided.

There is only one universal principle of problem-solving: the cost-benefit analysis. Every other principles only offer value as heuristic approximations. This is the calculus by which an expert must weigh the relevance and generality of any other principle.