Ovation Ventures Ovation Developer Docs

Policies

Code Quality Standards and Review Guidelines

By Ben C. Forsberg

This is a guide for practicing thoughtful code reviews to ensure consistency and quality across all our software product. This is a living document, and policies might change as we work with them. Your input is valuable. Please do not hesitate to make comments and start discussions about how this policy should be improved. The goal of this policy is to be pragmatic. No code review is going to be perfect. No two coders will write the same code. It is not productive to reject a code review because it’s not how you would have done it, or for purely aesthetic reasons (though aesthetics should be a part of your evaluation). However, it is also not productive to be too lenient. Remember, you may have to modify this code in a month or a year, or be called in on a weekend to deal with some critical bug.

What Does Good Code Look Like?

No two coders will write the same code. This is a creative discipline as well as a technical one. Therefore, we don’t want to be too prescriptive. At the same time, these are some good rules of thumb you should keep in mind when structuring your code, and when reviewing one another’s code.

Short Functions with Self-Descriptive Names

Limit functions to about 10 steps; all described by a short function name; with no side-effects.

Considering each function as a step in another function’s list of steps, that’s how its name should read: short, and self-documenting. If what your function does cannot be summarized in a very brief function name, it is probably doing too much. More specifically, it probably has side-effects that are a sign of code that needs to be refactored. If a function does exactly what its name says, and nothing else, and the function name is very short, then there’s no need for a comment. That’s the goal.

Shallow-Nesting

Never nest loops or conditionals more than three levels deep; if the inner block is more than a couple of lines, don’t nest it more than one level deep.

Another sign that it’s time to refactor your function is when you wind up nesting your loops or conditionals more than a couple levels deep. Each pair of curly braces (or indents in Python) represents a branch of the decision tree, and a new dimension in the matrix of possibilities. People aren’t good at imagining more than three dimensions at a time, and two is easier. When, exactly, to break your inner loop into its own function is your call, but the more logic goes in the loop, the shallower the loop should be. E.g. a one-liner can go three brackets deep, but if it’s more than a few lines, it shouldn’t be more than two level’s deep. A block the size of a whole function (or about 10 statements; see “The 200-Line Function” below) really should be flattened out. Flattening your function doesn’t change the complexity of your algorithm, but it simplifies what the developer, and the reviewer (including yourself several months from now) has to keep in their brains at any one time to understand your code. Review “Big-O Notation” for evaluating the complexity of your algorithm. Are you doing something in O(n²) (or worse) that could be done in O(n log n) or even O(n)? Can you unwrap one or more of those nested blocks and make your code dramatically more efficient? Along with that, try to keep the Happy Path un-nested. Your function will be easier to understand if the main logic is all at the same level, as much as possible. Refactor error handling so the exception gets the indented block, and the happy path stays outdented.

DRY Code

Don’t copy and paste code; write a function instead.

DRY means “Don’t Repeat Yourself”. It means: don’t every copy and paste code from one place to another. The problem is: if you find a bug in one implementation, how will you know you’ve found all the other identical implementations and fixed them? If you need the same code in more than one place, and it’s not the most rote, ubiquitous boilerplate code (ahem, Golang), it really should be abstracted into a function (or a macro, if your language has those).

Clear Interfaces (Law of Demeter)

Don’t do runtime type switches or dig into an object’s internal memory; methods should be black boxes.

Naturally, in order to tackle any problem of any but the simplest complexity, you’ll have to break the problem into simpler parts. Whether this is just breaking the problem into functions, objects with methods, re-usable UI components, separate libraries, or even microservices, you should consider each part to be its own, complete mini-program. Encapsulation is an important part of good software design. Each component of your program has memory that only it knows how to access in a consistent manner. That memory should be kept private and secret, so only the closest code can use it. To the outside world—consumers of the component—your component should be a black box with clear inputs and outputs, but a complete mystery between them. In particular, if you find yourself writing type switches to handle a variable differently based on its runtime type, that’s a good indication that you’re violating the Law of Demeter: you have too much information about the internals of distant code. Thats’a bug waiting to happen. Instead, make the type have an interface, and let it decide on its own implementation. Another important consideration for writing good, encapsulated code with clear interfaces is avoiding side effects. If you have a function called validate_credentials it should not be sending off emails or creating records or doing anything that is not validating the credentials. Split those other activities out into other functions, and call them explicitly.

Types Are Friends

Don’t do runtime type switches, use interfaces instead; limit use of dynamic types to error handling and parsing external input.

A lot of languages have dynamic types that make it easy to write code quickly. These are good for quick scripts to automate tedious tasks, or to make little widgets on your web page do a little action, but this friendly laxness really works against you when your code becomes more complicated. JavaScript was originally written as a kind of novelty language to make documents do some interesting things. Now it’s developed into a serious application platform, and so we have TypeScript. Python has graduated from a wrapper to orchestrate C libraries into an Enterprise development platform in its own right, and so Python3 introduced type annotations. Here is the thing about strictly-enforced type constraints: they move bugs forward in the development process. They turn business logic errors that might make it into production into interpreter or compiler errors that will never see the light of day. With LSP servers, these can be shown to you right in your code editor as you are typing. Consider a library that deals with geometry. Perhaps it’s part of a graphics library. In Go, you can make a type alias for float64 types called Length and another for Angle . You can put methods on Angle like Sin , Cos , Tan that return values of type Length , and similarly Length can have methods like Asin , Acos , Atan that return Angle . Go lets you do normal arithmetic expressions with Length and numeric constants, and with Angle and numeric constants, but it is a compiler error if you try to do arithmetic with a Length variable and an Angle variable. And that’s as it should be: that doesn’t make any sense, geometrically. By making those type aliases, you’ve made the Go compiler aware of your business rules, and so errors you might write can be flagged and shown to you very early in the process. A language like TypeScript has optional type annotations. You should consider these mandatory, and use them whenever possible. You should never have to check typeof . Instead, use TypeScript annotations to enforce the type. If you’re checking typeof , and you find the wrong type, you’ll find it at runtime. If it gets by testing, then it’s an end user that will find your error. Instead, if you use the type system to enforce the type, then you will find your error before you even commit it. As mentioned above, you should never have to do a type switch at runtime. Instead, require that your argument implements some useful interface, and call those methods. This interface will be its own sort of documentation, describing the purpose of the types that implement it in your algorithm. Some places where it is acceptable or unavoidable to deal with runtime types (if your language supports them) are:

When to Comment Your Code

Comment your code if it took you any significant time to figure it out, or for your reviewer to understand it.

People have a lot of opinions about this. Some people say to comment everything, because you won’t remember what you were thinking 6 months from now. Some people say code is its own documentation. Naturally, the best answer will be somewhere in the middle. If you are really writing short functions with no side effects and short, pithy names, that should be its own documentation. However, that doesn’t always happen, and comments are necessary. Some clues that it’s time to comment your code:

The 12-Factor App

Use the advice of “The 12-Factor App” to make web software architecture.

The “12-Factor App” is a set of 12 architectural recommendations for cloud-native, “software-as-a-service” applications. These recommendations include advice for the entire lifecycle of the application. Of particular relevance are the section on configuration, backing services, processes, and concurrency.

Common Mistakes and Alternative Solutions

Magic Numbers

Don’t hard-code constant values. Instead use defined constants or config parameters.

A “Magic Number” is any constant except 0, 1, true, false, and nil (null) that appears anywhere in your code except in a header where these constants are defined. These can include string values like "production" . After all, on a computer, everything is a number. You should avoid these, replacing them with named constants. Why are they bad? A number of reasons. For one, every “Magic Number” represents some business rule, some value that is decided outside of your code and is therefore subject to change. When they do change, you should be able to change them in one place (DRY). Also, if you have several “Magic Numbers” that have the same value, but represent different things (e.g. 60 seconds in a minute; 60px of padding; 60º phase differential between signals on a line), you won’t be able to easily change them without understanding what each individual 60 that comes up in your search is doing. Many of these “Magic Numbers” may never change, but you should at least think about where that value is coming from, and whether it should perhaps be a configuration variable. (See “12 Factor App” above.) For another, if you meant to type "production" 18 times, and you typed "produtcion" once, your LSP won’t catch that for you, but if you have a constant PRODUCTION , you’ll catch those typos before going to production. (I have never once typed "from" when I meant to type "from" and "form" when I meant to type "form" on the first try. Also, I don’t know what kind of particle a functino is, but it’s always irradiating my code.) If you’re comparing string constants, they really should be integer constants. Comparing strings is expensive, while comparing integers is practically free. Ruby and (recent) JavaScript have “symbols” that reduce strings in your code to integers in the IR. That is very efficient, but doesn’t help with the typo problem. If you’ve got a string constant, ask yourself what you’re comparing it with. If it’s not a string coming from outside (say, an API), could it be an enum constant? Lastly, giving these values a name makes your code easier to read. Your future-self will thank you.

Linear (and Worse) Comparisons

Avoid sorting or comparing arrays and strings, if you can. Instead, use enum constants or symbols.

Strings are the most common type of variable you probably work with. Also: strings are the worst type of variable you probably work with. In C, they’re unbounded arrays of bytes. In more modern languages, they’re often UTF-8 encoded, which means that each letter might be a different size! Comparing two strings together involves a lot of code under the hood to check and validate byte sequences one after another after another. Whenever possible (and it’s often not possible), avoid directly comparing strings, especially sorting strings. Sorting seems to have a hard limit on complexity of O(n log n) (though it can be worse!). Sorting strings means that you’re doing O(n log n) times the average length of the string individual comparisons, each involving checking for multi-byte UTF-8 characters. You’ll have to do it, but defer it as much as possible and make sure you’re not doing it more than you need to. Many languages—Java/TypeScript included—have “symbols”, which are strings in code, but reduced to integers in the language’s IR. These can be a good alternative to working directly with strings. Hashes (dictionaries, objects, etc.) also work by reducing each string key to a number. However, collisions are possible, and hashes only reduce, not eliminate string comparisons.

Squashing Errors

Don’t ignore errors. Instead, try to solve errors if you can, or at least report them if you can’t. Be specific when you handle errors.

Errors are friends! You’ve done the work of using types and constants wherever possible. You’ve moved every possible error from run-time to development-time. But there are still some things you can’t know until your code is out in the real world, talking to other real world systems and—horror!—users. The unexpected will always happen eventually, and when it does, you have two choices: You can try to cope with it, or you can pass it up the stack and hope somebody up there knows how to cope with it. What you should never do, however, is hide it. Sometimes, you’ll get an error that you know is no problem. In the C standard library, reaching the end of a file you are reading presents as an error. In Go, when an HTTP server shuts down, it always returns an error, even if that error is ErrServerClosed . Good news! That’s one of those rare occasions where you can actually handle an error rather than logging it and unwinding the stack. Write a handler and at least a comment explaining why that error is nothing to worry about. Always try to be as specific as you can with the errors you catch. In Python, for example, you can catch Exception , but that is the very top of the exception tree, and includes things that should not ever be caught, like syntax errors! It also includes things that are, in Python terminology “exceptions” and not “errors”, like coming to the end of a loop. Separate out the errors you know how to handle from the errors that are truly unexpected and should, properly, crash your program. (Sometimes, a program crash is the best scenario, if data or memory corruption could happen.)

The 200-Line Function

Limit functions to about 10 steps; break long functions into smaller steps; refactor into object methods.

You have a complicated problem to solve. You make a function solve_problem() , and you get to work describing the steps you would take to solve the problem in a language the computer understands. First, you do this thing. Next, take the result of that and do this other thing. One step after another. And when you’ve finally come to the answer you’re looking for, return that. One problem, though, your function is now four screens long in the GitHub pull request. Unless you are optimizing some C (or Rust) and really care about the overhead of a function call (in which case, macros are always an option), you should try to keep your functions as short as possible. Some tools, like Rubocop, come with built-in rules limiting you to a certain number of lines. These cut-offs are arbitrary, and should be taken with a grain of salt. Also, the reasonable number of lines of code will vary with the language. 10 lines of Ruby should be equivalent to maybe 30 lines of Go, since Go can require three lines of error handling for each function call. Furthermore, too-strict adherence to some arbitrary line limit encourages “Code Golf”—trying to do the most logic with the fewest bytes—which is counter to good coding practices. The point, however, is that your function should be about a paragraph’s-worth of information. It should take about the same mental effort to understand each function as it takes to understand one paragraph of your favorite natural language. Consider 10 “statements” (function calls, complete with their error handling or other boilerplate) as the arbitrary, and easily bendable limit. If your function runs much longer than this, you should break it into smaller functions. Your top-level function should simply list the steps of its algorithm, where each step is a function it calls. It is okay if a function is called from only one place in your code, because human developer time is more precious that processor time. Another thing to consider: when breaking up a function into shorter, smaller functions, you may find that you’re threading a lot of variables through. If this happens, chances are you’d be better served by making your functions into methods of an object. The threaded variables become the object’s (probably private) properties. There are many pattern names for representing an algorithm or a process with an Object: Functors, Strategies, etc. Consider if there is one variable that a group of functions all require in common. Perhaps these functions should all be methods of that variable’s type.

“Cleverness”

Prefer simple and expressive code to compact and clever code.

We’ve all done it: we’ve all tried to find the most “efficient” use of the language to get the most done in the fewest keystrokes. Or tried to use some side-effect of library code to obliquely accomplish our task in a magical-seeming way. We’ve all wanted to be the hero that coded Q_rsqrt into Quake III Arena and then to lean back, let our pixelated sunglasses glide down onto our faces and call ourselves `1337 HaXXORs. Don’t do it! Aside from completely confusing your fellow devs (and your future-self), this kind of code is extremely fragile, because it depends on a lot of assumptions about things beyond your control. Once those assumptions change, good luck trying to debug the “magical” code some asshole (your past self) wrote. I remember the rude awakening the first time a reviewer called my code “clever”, and meant it as a pejorative. But I’ve since come around. “Clever” code is not good code. KISS: Keep It Simple, Stupid.

DSLs

Think twice about writing domain-specific languages to solve a problem; then think a third time.

This is my personal weakness. Whether your Hildegard von Bingen recording your mystic visions in your personal lingua ignota, or Anders Hejlsberg extricating Microsoft from the hot water they got themselves into with the US Justice Department, for some of us (and I am one) the urge to make languages is one of the things that make us feel human. However, consider this: who will want to learn your new language? If you’re doing this to solve a problem, are you actually making a new problem instead? Other developers will have to read your documentation and understand your grammar and, basically, understand the problem in the same way as you in order to use your solution. Are you making a greater intellectual burden for them? Do you want to be the guy that inflicted Regular Expressions on the world? There are some cases when a DSL might be a good choice. One is when you don’t have final business requirements for a feature, or you anticipate that requirements may change frequently. The art of computer programming is often not about solving the problem at hand, but about solving the meta-problem: the problem of solving the problem. DSLs are a way of solving the meta-problem, but they usually smell of over-engineering.

Secrets

Always use properly classified secrets; never commit them to GitHub.

A special type of “Magic Number” is the “Secret”. It’s the shared constant that allows access to some attached service (see “The 12-Factor App” above"). Secrets are a special problem because the running app needs access to them, but the user of the running app must not have them. In addition, developers will need to be able to create them and handle them in development environments, but access to them should be limited to only those who need them. Secrets are handled in-depth in a separate document, but here is a summary:

Tests

Happy Path Tests are Documentation

Write Happy Path tests to demonstrate the correct usage and return values of your functions.

Sometimes tests feel like a chore. Also, sometimes documentation can feel like a chore. You can halve your work by making it the same chore. Happy Path tests show users how to use your function and what to expect from their return value. As such, they typically require very little framework to set up and run. However, Happy Path tests are insufficient on their own as tests. A function or feature with only Happy Path tests should not be considered to be tested. You need to explore the ways in which the function or feature can fail. Does your function raise an error if it is misused? Prove it! Tests are a way for you as a developer to play with your code and see what it does. You should take the opportunity to explore its edges and anticipate how it might fail if abused.

Armor Your Code Against Your Future Self

Assume you will need to maintain your code long after you’ve forgotten what you were thinking about when you wrote it. You probably will.

Imagine you have to dig into some obscure code to fix a bug, or change some behavior. This code is a spaghetti of “clever” solutions, obscure language features, and side-effects. What idiot wrote this mess? Oh. It was you, last year. What were you thinking? When you write code, imagine yourself in a month or a year having to come back and maintain it. Will you remember what you were thinking? Write your assumption checks, error handlers, and tests so that your bumbling future self can’t screw up your nice, new code by putting in the wrong parameter, or otherwise using your code incorrectly. Your future self is always out to get you. Don’t let them get away with it!

Coverage Targets

Use common sense.

At this time, we are not making a recommendation for a specific testing coverage target. Some things are too obviously simple to require tests. Other things, especially on the front end, are easily testable manually, or the side effects of them being wrong will be obviously evident when the site is viewed. However, you should be careful in writing and reviewing code not to take a function’s obvious correctness for granted. Something that seems obvious now will seem less obvious in a year, or might not be obvious at all to the next coder who didn’t have to figure out how to make it work like you did. The further toward the back-end a function or feature is, the more important it is to have tests for it to demonstrate that it’s working and to prevent changes from introducing errors later.

Code Reviews

What Goes in a PR?

Keep concerns and tickets separate; small code-quality fixes are acceptable.

We’re all juggling multiple projects at the same time. Is it better to chunk work together, or to finely split your work out? It may seem like you’re creating less work for a reviewer by including several tickets into a single PR. However, the reality turns out to be the opposite. Reviewing someone else’s code involves trying to get into that developer’s head to figure out what they were thinking. The more features that are included in a PR, the harder this is. Large PRs are going to take longer to review and, contrary to the intention, wind up blocking the development workflow. You will certainly run into the situation where one of your PRs depends on another one. You should try to avoid this as much as possible, but it’ll happen nevertheless. In that case, it becomes particularly important to keep the changes in each PR specifically related to the objective of that PR. It becomes especially confusing for the reviewer to try to understand what they’re looking at when it’s a point-in-time snapshot of an on-going process. If it’s harder to review, it’ll take longer to review; if it takes longer to review, it’s more likely to create or compound this awkward situation. Remember that you can comment on your own PR. Address any comments that are directly related to the scope of the PR, but add a comment like “Fixed in PR #512” to any fixes that properly belong to a different scope. You can even comment the code directly, since you know you’ll be removing that comment in the later PR yourself. Sometimes, while you’re working on something, you’ll notice something unrelated that needs fixing. If it’s something small—like an incorrect or ambiguously-named variable, or white-space that doesn’t match the project style—you can go ahead and be a “Gnome”: to clean as you go. You should leave a comment on your PR in that case explaining what the change is, and why it’s not directly related to the ticket. (In this case, do not update the code directly. That will be more confusing than enlightening in the future.) Gnomish updates should only be a small fraction of the changes in a PR. If the update winds up being a whole refactor, or if your gnome fixes dwarf (no pun) your in-scope changes, then they should go in a new PR. Create a new ticket—perhaps a sub-task ticket—for your new PR, or it won’t get reviewed.

Who Should Review Your Code?

Not you.

After you’ve written the code and solved the problem, you’re too close to the code to see it properly. All your code seems obvious and inevitable after your struggles. You can’t see how unexpected your solutions are, or the assumptions you made that might not turn out to be true. Ideally, you should get a review from someone else who is familiar with the language and the project. That is often not possible if you’re working on something new, or something that is its own silo. Also, if you are working on something that’s becoming a silo, it is good to get a review from someone who is unfamiliar with the project. That will both bring fresh eyes to the project and spread the knowledge about it. If you’re going to request a review from someone unfamiliar, you should probably request more than one review from different people: someone familiar and someone unfamiliar, or at least two unfamiliar people. A walk-through of your code is always a very good idea, especially if your reviewer is new to your project. That’s usually very interesting and informative. Schedule a meeting to present your code, and then allow them time to go over it on their own afterward to come up with their own opinions, comments and requested changes.

When Should I Reject A Code Review?

If you see a bug; if you see a security hole; if you are confused.

Schedules can be tight, and sometimes it feels like you’re holding up a project by requesting changes. It can feel like you’re pestering the poor developer with change requests, and you certainly know how it feels to be on the other side. Never, ever let a review pass if:

You probably shouldn’t let a review pass if:

On the other hand, be wary about trying to make other developers write code exactly how you would.

What About AI Reviews?

Use AI reviews as an initial check before submitting your code to a human; use as a second (or third) reviewer.

AI is still young, and it makes many, many mistakes. It might get better, or Oroboros might already be starting to consume too much of its own tail. Don’t rely on AI checks for anything critical. However, to paraphrase Sartre: “Hell is other people’s code.” Reading other people’s code is boring, and people get anxious to get back to their own tickets. When that happens, subtle bugs and security flaws are easy to miss. AI should be used as a back-up to supplement a thoughtful, human review. Never a replacement.