5 Tips for a New Codebase

Lately, I’ve been thinking about starting new repos for some projects and looking at a few different start-ups’ code. Below I’ve captured a few quick tips on starting a new codebase:

1. Use English.

The best engineering talent in the world reads and writes english. It’s a prereq to keeping up-to-date on the latest technologies or contributing to open-source projects.

At some point in the future, you might want to outsource something, have a consultant advise you on some aspect of your code, or even sell your company to someone else. Why limit potential partners to those who only speak your local language?

2. Tabs not spaces.

Or the reverse. I don’t care – the point is don’t waste time arguing or researching issues that are 90% arbitrary questions of taste. Anyone who emails your team list about changing should be fired. Or at least forced to buy everyone else a beer.

3. Git not Hg.

It works. More importantly it’s popular and well-known. Why make people learn something new to work for you if the “standard” tool is just as good? I prefer the elegance of Hg, but it just doesn’t have the following that Git does.

4. Use known code standards.

Don’t write your own. Having done so a couple times, trust me: you have more important things to do. Most engineers will imitate what they see in your code base, rather than spend time reading your standard. To find a standard to reference, Google Style Guides is a good place to look; or your favorite open source project; or the engineering blog of your favorite company.

5. Document in code, not in a wiki.

Wikis are chronically incomplete and out-of-date. The best way to write documentation of what your code does is in the code itself.
It’s the first place whoever needs the documentation is going to look.
The documentation will follow the code through the workflow. You don’t need to worry about a developer making changes on a branch that has yet to be merged to live. When it’s in live, the documentation on live will be updated.
It’s easy for the reviewer to verify that someone changing code has properly changed the documentation.


A common theme from these: while the “clean slate” of a new project or company might seem like a great opportunity to follow your own preferences on issues like the above – be careful. Indulging your personal preferences can come at the cost of lengthening the learning curve for those who join your project in the future.