#4 Coding/Drafting Best Practices

Photo by Daniel McCullough on Unsplash

It was my first corporate law job as a 1L (i.e. I was still in law school) and I remember asking Andrew Demetrious if there was a standard drafting guide I could read to get the rules for contract drafting. He laughed and responded with something along the lines of “There are some guides, but the reality is that lawyers learn to draft by reading and negotiating agreements.” Fine, so I showed up to the office at 5:30am every day that summer, printed 10–15 agreements that were available on the system and read through them before it hit 8:30am, at which point I would switch back to what needed to be done that day. There’s no secret to getting better, it’s about putting in the work.

I was jamming out some late night notes for the engineering team and realized how much I code the same way I draft legal agreements. I also realized how much of the same best practices for coding also apply to drafting legal documents:

1. Please pseudo-code before you actually code. ⇒ What legal effect/result are you trying to achieve with the words that are you are putting down? Write your intention in an outline format in plain language first, then go in and include the technical legalese that's necessary. I used to have people walk down to my office and ask me how I would draft something. I'd just ask them to explain it to me, and then I'd say "Yeah, write that down and you're good to go." You'll find that by explaining something to yourself, it'll be easier to craft the logic and the language necessary to get it done.

2. Comment extensively. I think it’ll be difficult to get me to tell you “Ok, well, that was too much commenting you did there.” Write comments for yourself two years from now, as if you'd forgotten all context around the function that you're writing and assumed it was written by someone else. ⇒ Draft clearly. If it's not clear on the first read, then redraft it. See next item for more:

3. Write code for other people, not yourself. Writing code that only you understand is not sufficient. When you formulate logic, you should be able to explain the logic to a business person / non coder simply by reading your code. If you can’t do that and it’s too difficult to explain, then the code is likely too complicated and should be simplified. Make no mistake: SIMPLE IS REALLY HARD TO DO SOMETIMES. In those situations, we try to supplement the complex logic with comments. ⇒ Keep your language as simple and straightforward as possible. There’s a super nerdy game in programming called coding golf. The goal would be to achieve some effect with the least amount of code as possible. While you certainly don’t want to obfuscate meaning by using too few words, try to draft language which captures the same concept, but in as few words as possible.

4. Use descriptive variable names and DO NOT USE single letter variables, ever. I know it’s super easy to use “i” and “j” as index vars for iterables, but the extra characters are free so be descriptive where possible. For example, instead of just “index” use “fileItemIndex” instead. That way if we're in some nested loop we don’t need to ctrl+f to find what index was defined as and we can immediately comprehend that it’s the index of the fileItem. ⇒ Use descriptive defined terms and avoid repeated use of acronyms where possible (unless your audience is guaranteed to be able to decipher it immediately).

5. Always return success and/or error objects. Example error object: {error:true, details: Include the try/catch error event details here or something custom, additionalDetails: {whatever you want}, errorLocation: “STRING NAME OF JS FILE WHERE ERROR OBJECT RESIDES”}. Example success object: {success: true, error: false, status: “successfully did something need”, result: {} }. ⇒ This one should be paired with pseudo-coding. Outline the logic you're trying to express, including the legal effect/result that you want out of a scenario. This is loosely tied with what I refer to as "Floating IF Statements." For example, I often see statements like this "If Party A fails to provide the services, Party B is entitled to damages." There's an implied 'then' keyword in the statement, but why would you rely on that? Put the THEN in there so the reader knows exactly what will happen.

6. Try to fail gracefully, document and handle your assumptions. That means whenever you touch something that could block the user or freeze the app (e.g. dealing with the filesystem), you need to wrap the method in a try/catch. Ask yourself “if this line of code fails, will it block the user from accomplishing something? Will they know or be able to report what the error is? Am I assuming some condition/key exists? What happens if I assumed wrong?” ⇒ If you're making an assumption about the current or future situation, document it. That said, don't overdo it by trying to outline EVERY single situation. This one also reminded me of a quote from the one and only Michael Roster "Good lawyers ask 'What if, what if, what if? The best lawyers also ask, 'So what, so what, so what?`"

7. Shorthand should be used sparingly. If you shorthand then it should be immediately obvious to another programmer what you are doing and you should include comments to provide context. Remember, you are not writing code for yourself, it’s for the benefit of others to read and comprehend.

8. Positive thinking/conditions wherever possible. I’m seeing way too much negative/inverse logic. !someVar is easily someVar == false. “But Tony, !someVar is so much shorter.” That's true, but “!” is so much harder to read than “== false”. Also people can’t resolve negative conditions, it always gets reformatted to positive/affirmative conditions so why not just start with the positive so people don’t need to translate. “But Tony, I’ve seen you use !someVar.” Yep, I’m not perfect either and was likely lazy when I wrote that. This is also not a hard and fast rule. If the code is super clear then it can work (e.g. if you can read the condition as “not” someConditionTest, then it reads as plain English and can be understood easily). !someVar is also not that egregious, but !notSomeCondition is an egregious misuse of the shorthand, because ultimately you’re testing for a truthy value by using a double negative. Simple English grammar rules apply here.

9. Multiple IF conditions can sometimes be simplified into a descriptive variable name. If you’ve got a beast of multiple conditions to evaluate (ex. Condition1 === true && Condition2 > 90 && Condition3 == “No_Air_Conditioning”), then we an reduce the conditions down to a variable that makes it super clear what we are testing for =>

`let checkIfCorrectTemperature = (Condition1 === true && Condition2 > 90 && Condition3 == “No_Air_Conditioning”) ? true : false; `

Which makes it super easy to read the if statement =>

`if (checkIfCorrectTemperature == true){DO SOMETHING}`.

You can take it a step further and name the desired condition what you’re testing for

`let isCorrectTemperature` so `if (isCorrectTemperature) ….``

=> You can use defined terms to summarize a chain of triggers too. For example, “If party X commits a breach which remains uncured for over 90 days (an “Uncured Breach”), then SOMETHING HAPPENS” and later on somewhere else “If an Uncured Breach, then — “

And that’s it! That’s all it takes to start writing more scalable and easily manageable code or contracts.

--

--

--

CEO / Chief Engineer of HyperDraft, Inc.

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

About Flux Protocol

Borg: Large scale cluster management system

{UPDATE} Mermaid Beauty Salon - Makeup & Makeover Kids Game Hack Free Resources Generator

5 common mistakes people make in Java – Part 1

Python User Defined Functions to Automate Athena Queries using Boto3

The Downsides of This Platform For Technical Writing

Web Scraping With No Effort. Python: BeautifulSoup, Grequests.

Depth First Search🎃

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Tony Thai

Tony Thai

CEO / Chief Engineer of HyperDraft, Inc.

More from Medium

Circe’s Discipline — How does hard work create magic?

Pack Your s#!+ in a Small Box

Guilt-Free Rest for Entrepreneurs

Evaluate this to Become Vastly More Productive: Consumption vs Production Learning