Break any of these rules sooner than say anything outright barbarous.

George Orwell

This whole website is a living document, but this page is especially living. These are strong beliefs that are weakly held, I'm certain many of these will change over time.

Some of these will seem trivial and obvious, but they are all written because I have seem them consistently violated in professional settings. These writing were initially intended to be a code practices guide, but they became just angry venting.

If you don’t have an automatic formatter set up I do not trust you

Do you even trust yourself?

Black/ruff for Python, Prettier for TypeScript. Format on save.

⌾

Avoid Mocks

Tests that mock many things are fragile. It will be unavoidable that you will need to mock side effects (Avoid Side Effects) such as network calls, but every mocked function is something that can (will) break in the future, likely in a way that is hard to detect.

I have seen far too many unit tests that boil down to "call function A, mock all the functions that function A calls". Tests like this are shallow, and will not last.

When you Favour Immutablility, your functions become easier to reason about, and often easier to test, since you have fewer side effects and your test can validate the return object.

In Python especially, patches often rely on STRING PATHS meaning they won't get updated by LSP renames.

⌾

Avoid Side Effects

Your teammates won't know what side effects your function has. Reduce the amount of time they have to spend tracking these down by avoiding creating them, where possible.

⌾

Don't add state if you don't need to

Every possible state you add is something you need to remember to account for. It also becomes something every future dev will need to remember to account for. Keep state variables as minimal as possible, especially when dealing with classes. If you are using a class as a namespace sure I guess that makes sense, but those methods better all be static.

If I see something like this cost = CostCalculator(start_date).calculate_costs_v2(data, end_date) I’m gonna be mad.

⌾

Don’t use varchar by default

This is the advice of the Postgres developers. Read this for more information.

⌾

back_populates is better than backref

Yes, backref is more concise, but it also creates attributes that only exist during runtime. I want to see every attribute (and type) in the code as I am writing it.

Even SQLAlchemy docs advise back_populates over backref.

⌾

Be Flat

Ceteris paribus, prefer flatter function call trees.

⌾

Collect Then Operate

Wherever possible, collect all the data you need first, then operate on it. Do not lazy load mid-calculation, one off database queries will inevitably be called 500 times consecutively by someone else paying less attention.

This also means testing is easier, as you can create all your test data outside of your services, and pass the data in whole.

⌾

If my editor can't tell me what type a variable is, someone has messed up

This means that inputs need type hints, and outputs can hopefully be type inferred.

In Python especially this is frustrating because many libraries do not provide comprehensive type definitions that are automatically assigned (looking at you SQLAlchemy v1.4). This means you will have to annotate yourself.

Life is so much better if you do this. For everyone involved. Turn on Pyright type checking, get angry when you see red squiggles.

# VERY BAD
async def run(self, params={}):
    pass

Python makes @dataclasses and TypedDict (or better yet, Pydantic) really easy to use, I recommend them highly.

Further reading: The CMD-Click Manifesto

⌾

Contain Pandas

Pandas is an incredible tool! Especially for data exploration. Sadly it does not allow type validation, making is difficult to ascertain what are inside pd.DataFrame objects outside of using a debugger. Remember, Command Click. When pandas transformations are needed, try to limit how much a single dataframe gets passed around, ideally keeping its entire existence within a single function with type information for the input and outputs. This will allow future developers to easily figure out what is in the dataframe. Sometimes passing a dataframe through multiple functions will be unavoidable, that's okay! Just be aware.

If you are passing a dataframe to a function, its a good idea to add a check on what columns are expected to exist. This should fail loudly.

⌾

Do not put anything in __init__.py

I hate __init__.py. It has an awful name, it encourages duplicating exports, circular imports, its difficult to type, hard to search for. I know it is required(ish) for Python module resolution, so create it in every file. But leave it completely empty.

The only case where I support re-exporting from this file is if you are creating a library.

⌾

Fail Loudly

Code that fails quietly will never be fixed.

⌾

Favour Colocation

Generally, things are easier to find when they are close to each other, e.g. if a type definition is only used in one file, include the type definition in that file! Don’t even export it if you can avoid it.

This is part of why Tailwind is so nice to use, all the styles are right there, in the one place they are relevant.

⌾

Favour Immutablility

Immutability in calculations is so so so much easier to reason about. Unless there are hardware/performance constraints, err towards immutability.

For any given function, you do not have to worry about your objects being mutated, only the return value of the function. All the logic that matters to the function you are looking at is within the function itself.

⌾

getattr() is a red flag

The only time I can think you might want to use this is when we have split table that share parent super class e.g. BaseUsage, Usage, GasUsage, LPGUsage .

(to be fair, I believe that we generally want to avoid needing that kind of abstraction)

Other than that, why do you need getattr() ? Is there a better way of referencing the attribute, that doesn’t break VS Code type inference? Remember, Command Click.

Reflection is powerful and also may be a sign you’ve gone too far.

This is cursed, do not do this:

...
    def per_day_metric(self, metric: Literal["spend", "rev", "client_saved", "usage"] = "spend", **kwargs):
        if metric == "spend":
            return getattr(self, "per_day_spend")(**kwargs)
        else:
            return getattr(self, f"per_day_{metric}")
...

⌾

Give Bad Things Scary Names

Things that are annoying get fixed. Have a legacy function that is truly disgusting, uses dodgy abstractions and produces footguns but you don't have the time to rewrite it right now? Give it a truly fucked up name, that reflects how ugly it is on the inside. Make the next developer feel bad for using this.

A great example of this is the React __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED.

⌾

Greppability is Valuable

Being able to run a text search over a codebase is extremely valuable. This is especially true at API borders (service boundaries), where one project will call another project and you need to switch codebases to find where that API definition is. Often the only decent way to find the relevant function in these circumstances is string matching (or extremely consistent file structures which we currently do not have).

If I am in frontend and I can see some data is coming from an API called GET /api/client/foo/bar it is much quicker for me to track down the API definition with a search for "client/foo/bar" than any other method. So backend will need to have "client/foo/bar" as a full string.

# BAD
router = APIRouter(prefix="/v1/usage-test")

@router.get("/result-calculation")
async def get(request: Request):
    ...

# GOOD
router = APIRouter()

@router.get("/v1/usage-test/result-calculation")
async def get(request: Request):
    ...

Further reading: Greppability is an underrated code metric

⌾

Please be careful with inheritance

Mixins can be a beautiful thing. If I can’t Ctrl+Click on your method name and have my editor take me directly to your method you need there better a very good reason. Maybe try adding some type hints and flattening your trees. Perhaps this is an extension of Command Click.

⌾

Name prefixes are good (sometimes)

It can be very useful to use a prefix when naming things, for example when you have many similar variables that you need to easily tell apart or a list of files of different kinds so you can group them together alphabetically.

A great example of this is found in the SvelteKit file route naming conventions, where all files related to routing are prefixed with a + so they all appear together at the top in a folder.

A time where name prefixes are not useful is when differentiating variable types, for example prefixing interfaces with I (aka Hungarian notation). This is not useful as my editor should be able to provide me this information very clearly. In the case of interfaces, VS Code highlights them in a special color, and will vomit errors if you misuse an interface as a variable. This convention is a relic of the days of yore, before decent language servers and usable IDEs. If we ever start writing a project in C++ I am willing to reconsider this stance.

Yes I know this is a convention in C# but it is not in TypeScript, and in the past has been specifically disavowed by the TypeScript team in the past (which is saying a lot since both languages were designed by the same guy):

Naming Conventions

In general, do not prefix interfaces with I (e.g. IColor). Because the concept of an interface in TypeScript is much more broad than in C# or Java, the IFoo naming convention is not broadly useful.

TypeScript handbook, 2015

If your editor can’t easily show you what type your variable is, you have made a mistake already.

⌾

Do not change the URL path if the screen hasn’t changed

For many screens we have a searchbar where you can select a location. If selecting the location doesn’t change the whole page, do not change the URL path, just update query params. Each URL route should reflect a whole page. This is particularly important in Next.js Pages Router as URL changes trigger full page rerenders no matter what. This will interrupt any an animations (and is inefficient).

⌾

Query params are wonderful

Query params are a simple kind of global state that can be stored in a link! That’s so useful! When using React and Next.js, using nuqs makes query params super easy to manage, as if they are useState calls! So please use it. It even supports date parsing, enums, and arrays!

For example, query params are great for storing what particular location you just selected, or for the tab that is currently active.

Query params also allow you to skip writing state models!

(they also don't trigger full page rerenders in Next.js Pages Router)

⌾

Prefer query params/request body to URL params

Putting variables into the URL path is inflexible and makes parsing things quite confusing. Query params are much easier to change down the line.

# BAD
/api/sites/<site_id>/<energy_type>/<time_resolution>
/api/sites/102/elec/monthly

# GOOD
/api/site?site_id=<site_id>&energy_type=<energy_type>&resolution=<time_resolution>
/api/site?site_id=102&energy_type=elec&resolution=monthly

Slightly unrelated, but also note that DELETE endpoints can only have query params, not a JSON body. Isn't that strange.

⌾

React prop type definitions should be inline and anonymous

Unless you have a good reason. Only example I can think of is components sharing props (this is rare) or interface perf vs type perf (but I am yet to work on a codebase where that mattered).

// BAD
type ComponentAProps = { 
  a: string;
  b: string;
}
function ComponentA({a, b}: ComponentAProps) {
    return <>{a} {b}</>
}

// BAD
function ComponentA(props: {a: number; b: string}) {
    const {a, b} = props;
    return <>{a} {b}</>
}

// I CAN LIVE WITH THIS BUT YOU'RE WEIRD
function ComponentA(props: {a: number; b:string}) {
    return <>{props.a} {props.b}</>
}

// LITERALLY THE WORST OF BOTH WORLDS YOU MASOCHIST
type ComponentAProps = { 
  a: string;
  b: string;
}
function ComponentA(props: ComponentAProps) {
    const {a, b} = props;
    return <>{a} {b}</>
}

// GOOD
function ComponentA({a, b}: {a: number; b:string}) {
    return <>{a} {b}</>
}

It is extremely rare that you need to use prop type definitions more that once, so the separate type definition is just adding boilerplate with no benefit. Yes I know that its annoying repeating the same thing twice in a row with the anonymous type, but its the best of a bunch of bad options. It should be maximally obvious what params a component needs.

Generally its good to keep types as close to their usage as possible.

⌾

It is extremely unlikely that your calculation needs state

Do you have some numbers and you need them to turn into some other kinds of numbers? Avoid State. When I say state, I don't mean a short lived variable to store a value before you loop over something, I mean a class attributed that is mutated in X number of times across different methods.

A good rule of thumb is "all stateful variables this function uses should be declared within this function and all mutations should be visible by reading this function"

Overuse of objects can result in object-oriented obfuscation.

⌾

If you do not have request validation I do not trust you

Do not create API endpoints that do not validate query params or request body. Do not create API endpoints that do not validate query params or request body. Do not create API endpoints that do not validate query params or request body. Do not create API endpoints that do not validate query params or request body.

If there isn’t a class definition with a Pydantic model in it or a Yup/Zod definition, ask yourself why. You better have a very good reason. This is as much for security as it is for convenience. If I can’t instantly tell what params your query needs, you have made a mistake.

This also forces you to be typesafe. Perhaps this is an extension of Command Click.

# BAD - No human should ever have to do this
data_type = params.get("type", None)
test_date_str = params.get("date", None)
site_id = params.get("site_id", None)
channels_str = params.get("channels", None)
last_active_price = params.get("last_active_price", None)
meter_num = params.get("meter_num", None)
identity = params.get("identity", None)
on_at = params.get("on_at", 0)
off_at = params.get("off_at", 0)
is_all_day = params.get("is_all_day", "no")
experiment_type = params.get("experiment_type", "sum")

⌾

Functions return types should not change depending on parameters

Functions should return None, return SomeType | None or SomeType . SomeType can be a tuple, but that tuple should always have the same number of arguments. Flags like calculate_cost(return_as_float=True) should not exist. If you must have multiple versions of the same function with slightly different return signatures, I should be able to access everything in a typesafe way. This either means there should be

• @typing.overload decorators providing all the typesafe variants of the function
• 1 function containing the core logic and a other functions that wraps it and does type conversion (Both should have type inference or type hints.)

⌾

Only use a getter when you care about the setter

I know that it looks prettier when the getter is simple:

class User:
    first_name: str
    last_name: str

    def full_name_1(self):
        return f"{self.first_name} + {self.last_name}"

    @property.getter
    def full_name_2(self):
        return f"{self.first_name} + {self.last_name}"


User.full_name_1
User.full_name_2()

but the bigger impact is obscuring the fact that you are making a function call.

The real power of @property is not the getter, but the setter.

You can define a custom setter with validation logic OR You can intentionally leave out a setter so that an attribute is read only:

class X:
    _name = 5
    @property.getter
    def name():
        return self._name

If you are not doing either of these things, property is just hiding a function call which may contain side effect, which is a practice I consider dangerous. I have seen network calls hidden get behind @property. Never do this.

⌾

Test Inputs and Outputs

Tests should have concrete inputs, and concrete outputs. If you are testing things that aren't concrete inputs and outputs, what exactly are you testing? If your output is a side effect then you mock it, but generally your outputs are data.

⌾

Lint+format in CI, not on commit

Commit should be fast. Don’t make me wait. Lint+format needs to be in CI regardless so let’s limit the speed bottleneck to being purely on PR CI.

⌾