Older posts...
Older posts...
28 Sep
How I'm going to land my dream job
28 Sep 2014
How I'm going to land my dream job
1 Oct
Neural net training fail
1 Oct 2014
Neural net training fail
13 Oct
Pow + SSL without the hassle
13 Oct 2014
Pow + SSL without the hassle
17 Oct
Using machine learning to rank search results (part 1)
17 Oct 2014
Using machine learning to rank search results (part 1)
23 Oct
Using machine learning to rank search results (part 2)
23 Oct 2014
Using machine learning to rank search results (part 2)
9 Nov
Managing complexity in Go
9 Nov 2014
Managing complexity in Go
25 Nov
Remote work: an engineering leader's perspective
25 Nov 2014
Remote work: an engineering leader's perspective
19 Sep
Running A/B tests on our hosting infrastructure
19 Sep 2016
Running A/B tests on our hosting infrastructure
19 Jan
Optimising Redis storage, part two
19 Jan 2017
Optimising Redis storage, part two
27 Mar
Every service is an island
27 Mar 2017
Every service is an island

Document and comment code? Or don't?

The stance on documentation in the Ruby community seems to oscillate between “RDoc the hell out of it” or “nah, the code (or the test suite) is the documentation”.

We think both are untrue, and have a pragmatic middle ground: “documentation” per se exists mostly under the skullcaps of team members, but some things do need minimal documentation.

This article was cross-posted from the HouseTrip dev blog.

I decided to try to write it down properly after receiving this email from Nilan:

Hey Julien -
One of the start ups I advise at the moment is going through scaling hell - (i.e. adding a load of developers to a monolithic code base)
As they ramp up devs (i.e. doubling the number of devs) - they are seriously considering spending a lot of time documenting their code base - this smells like a bad idea - my general steer would be to focus that time on writing good well commented code and ensuring you have a well documented pull request process.
Would you ever advise a startup to write documentation ? Sorry if this is an open ended question

I’d never advise anyone to write detailed documentation. That typically falls out of sync with codebases quickly unless you’re really anal about it, and can afford the enormous time wastage.

Well designed code doesn’t need much documentation, but in my opinion, it does require at least these basics.


There should be established and respected guidelines and standards. At HouseTrip we enforce those through code reviews.

This reduces the need for documentation, as having consistent tools and ways to use them acts as a lingua franca.


Naming in the codebase should be excellent. Classes, methods, project names should map closely to the domain. Naming should be debated.

Like the above, good naming avoids misunderstandings with your future selves (and teammates). Anyone who’s worked with me knows I can stall progress on a project at the whiteboarding stage until we nail how we’re going to name things (URL resources, classes, repositories, etc.) and I firmly believe that’s well invested time.


Each project (repository) should have a good README, stating at a minimum the project’s manifesto (what are we trying to solve, what are the principles we adhere to), how to install it and play with it, how to deploy it, basics of its (external) API, and a set of block diagrams giving an overview of the internal architecture. Here’s a possible example.

Typically, we start projects with the README. We do our best not to discuss internals, architecture, or even what technology we’ll use until that’s written down. It’s normally our first commit in any repo.

Smart comments

Any part of a method/function that requires some thought, has anything hacky or contorted, should be commented.

My motto is “if you have to think twice before writing it, it needs a comment”.

Simply put, if you had to take time to write your head around it, despite having most of the domain in mind already, your future future self (or others) are likely to be unable to make heads or tails of it. No amount of specs are going to save you.

The key thing to remember here is that code gets written once, edited a few times, and read countless times over the lifecycle of a software product—all that by different people if it’s successful.

Brain storage

No single engineer should ever be the only one with intimate knowledge of part of the codebase.

This is, incidentally, an argument to actively limit the number of different technologies in use in a company, otherwise that goal is much harder to achieve (amongst other issues). This also means you can’t have less than two people coding on any project.

Pair programming, shuffling teams, and leaning on long-time team members for mentoring, and importantly retention are key here.


Yes, documentation is important. But where documentation was simple in the waterfall days, the fat stack of paper—or the fat stack of RDoc—doesn’t quite cut it anymore.

A combination of well-thought, minimal starter docs and trusting in the brain power of the collective is a means of documenting code that we think maps better to an iterative, decentralized practice of software engineering.

Agree? Disagree? I’d love to hear your thoughts - I’m @mezis_fr.