What is Good Code? The Legal Contract Analogy

Title

What is Good Code? The Legal Contract Analogy

Date
December 15, 2020
Tags
CodingTech Analogies
image

This is part of a collection of posts addressing communication between tech and non-technical. Code is a highly abstract systems that has only been common over the past 30 years yet is all around us. It's important we find ways to describe each other's work in a way that is addressable to everyone.

Analogy: Code is like a legal contract. Both are procedures built from highly complex webs of declarations, processes, and if/else statements.

Legal documenting is an application of business logic into a legal framework. Code is the application of business logic into a technical framework.

Qualities of good code

This is my subjective opinion in order of importance:

Readability

Code should be clear enough that someone else technical can read it and understand what it is there for. If it's very clear a non-technical person can kind of understand what it does. Naming your function addCalendarEvent is much better than add.

Maintainability

Changes will come. APIs, software, and codebases get updated all the time. It's a constantly shaping field. It's important to design code in a way that additions, removals, and edits can be done without having to rewrite the entire code base.

Effectiveness

It should do what it is supposed to do in a way that doesn't waste resources. Code should be ready to manage situations when things don't go to plan and not tear apart the whole code base.

Legal Contracts

Legal contracts are a good analogy for code. Like I said earlier: both are essentially applications of logic into their own mediums. The qualities of good contracts can be

Here are my thoughts on what makes a good contract:

Readability

A legal contract should make sense to anyone. The landlord that gives you an impossible to read Renter's Agreement is probably not someone you want to rent from! It is bad practice to make legal documentation unapproachable.

Maintainability

Laws change like APIs. What if the laws in your registered state change and you need to make amendments? A good contract allows for amendments and additions without a complete restructure.

Effectiveness

Does the contract do what it's supposed to do? Does it protect? Does it provide considerations when things don't go as planned? What if the business needs to take out a loan? Does the contract try to enforce things that are illegal?

Extractable Analogies

Spaghetti Code ⇒ Spaghetti Contract

Imagine reading a contract where every section references three other sections. You have to move here and there yet you also find the same sentences duplicated. Tough to read. Sometimes it's fine, but sometimes it is really really stinky.

Secure Infrastructure ⇒ Bulletproof Contract

Secure contracts take effort, knowledge, and experience. So does code.

Verbose code and contracts can be smells, but aren't necessarily bad

Saying short code is better than long code is like saying short contracts are more streamlined than long contracts. A lot of times yes, a lot of times no.

Code and contract length often has to do with making sure all the loopholes, edge cases, and contingencies are managed with consideration.

Final Thoughts

Code is highly abstract and hard to understand, yet tech is all around us. I think analogies help. Legal scripting may also be abstract, but it's hard to find anyone who has never had to sign a paper. By using one to explain the other, I think we can help in how we communicate to friends and coworkers. Hope this analogy helps you!