I’m sure this resonates with lawyers! Both lawyers and software engineers:
- use words in a formal way to meet a functional or legal requirement;
- often have to change something that has evolved over a long period of time, originally created or extensively edited by someone else;
- reuse content to work more efficiently: software engineers reuse code from libraries and write new functions to be reused within the codebase, while lawyers adapt existing contracts or cut and paste clauses from an existing contract; and
- add content to meet requirements that may disappear over time, but which is maintained regardless.
Taking the wider view
One measure for code effectiveness is execution speed: how fast does it run? But from a broader perspective, software engineers consider how quickly someone new to the codebase (or themselves, returning to the codebase after working on something else) can understand it, in order to change it. Arguably this is more important than raw execution speed, because it means that the organisation is able not just to deliver the functionality needed, but to do so reliably and to add more functionality over time. This is why well‑written code, with good documentation, is so important: it’s not enough that the code works, it needs to be well written so that someone can understand and change it. There’s a saying:
“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability.” – John F. Woods
But deadlines need to be met, and code may be delivered that meets the immediate requirement but would be hard to understand and maintain. This is one of the reasons refactoring was introduced, as a way to improve how the code is written (making maintenance and future work easier) without changing what the code does or how it interfaces with other software. To address this, software engineers refactor code. This might involve:
- reducing complex conditional statements and breaking long methods into smaller, single-purpose functions;
- putting commonly used code into reusable functions;
- making the names of variables, functions, and classes clearer;
- splitting large blocks of code into smaller, more modular components;
- removing duplicate code by applying the ‘Don’t Repeat Yourself’ principle; and
- adding comments and formatting code consistently.
Why you need to smell your contracts
Contracts are often written as though the only thing that matters is the robustness of the legal provisions: this is the contract equivalent of software that delivers functionality at the expense of understanding and maintainability.
In software engineering, the term ‘code smell’ (which I think is fabulous!) is used to describe a sign that the code may need refactoring. In legal documents, ‘contract smells‘ include:
- Text you don’t need: This is the low‑hanging fruit of refactoring: phrases like ‘from time to time’; ‘nothing in this contract’, and ‘set out below’. Many contracts include definitions that are in everyday use: if they are in common use, you don’t need to define them.
- Wordy phrases: Some text is just too long, for example ‘includes, but is not limited to’ can be replaced with ‘includes’: ‘is not limited to’ is implicit.
- Long clauses or sentences: Can you read your sentence without drawing breath? Is the clause trying to cover too much? Consider breaking it down into multiple sentences or by using bullets.
- Legal language: Most legal documents are written as though the only audience is going to be other lawyers. Replace legal terms with more commonly terms.
- Wall of text: Is the content easy to navigate with clear headings and structure, or is it an intimidating wall of copy?
- Monolithic formatting: Does the contract use SHOUTY BLOCK CAPS or more relaxed typography?
Addressing these contract smells doesn’t change the legal meaning or robustness of a contract, but it does make it easier to understand and extend. One of the common misconceptions of legal design is that ‘easier to understand’ is just aimed at non-lawyers: this is simply not true. Put someone – even a skilled lawyer – under stress and give them the choice of working with a contract that is a wall of text or a contract that uses well-structured, easy to read text, and they will choose the better design every time.