You are coding up the next startup to be acquired by one of the Internet’s behemoths. Your team is small, each member has their own role and is responsible for disjunct portion of the code base. You know your code inside and out. You know exactly how everything works, were everything is and what is used when. All you need is a few TODOs here and FIXs there, maybe even a few tests and you’re fine, right?

Building a product is a team effort

You think you’re OK but you’re not alone. Your team mates with whom you’re building the next big Internet success might have to cover for you when you’re on vacation or fix your bugs that made it into production. Do them a favor and write your code so that others can follow along. That those who are new to your work can understand what each function, method and class does. How they fit together.

You think you know, but you don’t

And by others I mean your future self included. Sure, you know your code inside and outside while it is still fresh. But what when you finish this portion and move on the next component? What happens when you revisit the code you just wrote, 6-12 months later after not having looked at it, let alone think about it for so long? Will you still know the decisions you made writing what your wrote and why?

Think about those who come after you

Recently I performed a code audit for Musea Ventures as part of a technical due dilligence of a potential investment opportunity for Musea Ventures. The team that wrote the code had moved on to bigger and better things. What remained was a snapshot of the code and an running production instance in maintenance mode.

Even though I am at home in programming languages used in this code base: Ruby and JavaScript, I had a harder time than usual to comprehend how their service was put together. Exactly because the code was not written with others in mind. While the server side code base was laid out according to Ruby on Rails' convention, there were many many unknowns.

First of, there was very little documentation inside or outside the code. Secondly, I couldn’t execute the code because key bootstrap and configuration files were not part of the code snapshot I had access to. The inability to execute the code rendered its test suit moot too. With packaging and deployment tasks as well as the routs file missing, there was no way of knowing how a production instance is put together or how (HTTP) requests are handled by the service.

How to be a good team player

It is not too hard write code that you, your team and those who pickup where you left off can understand much easier. A few simple practices will go a long way. Keep up with those listed below and you will thank your self in the future.

1. Keep functions and methods small. I mean really small. As a rule of thumb, a function or method should fit on a single screen. Use tools such as [Saikuro])http://saikuro.rubyforge.org/) and Flog to find functions and methods with high complexity scores and refactor them into smaller, simpler functions/methods. Find code that is repeated and can be factored out into a separate function/method with tools like Flay.
2. Describe each function and method with an inline documentation notation. Describe what the function/method does. What input parameters it takes. What the response of the function/method is. For Ruby there are a few notations to choose from: RDoc, Yard or TomDoc for example.
3. Keep a README file with instructions how to run the code. Describe the steps to setup all dependencies, including APIs that will be used, persistant storage (SQL DB, NoSQL server, etc). Provide step by step instructions how to debug the code. For example, how to run a debugger, how to set breakpoints and so on.
4. It you don’t check in configuration files with sensative information in them, such as database passwords or SSL certificates, be sure to describe in the README how to optain this information.
5. Maintain a test suite that covers your code base well. A good test suite does a few things. It forces you to think about the behaviour of your functions and methods. This will help you write more singular functions and methods. It makes refactoring easier as one finds out instantly if refactoring breaks any test. Use tools like Rcov to keep track of the test suite’s coverage of the code.
6. Write meaningful commit messages each and every time you check in changes to your version control system. (You are using Git aren’t you? If not, you should.) Use your version control system’s annotate (aka. blame) function to pull up these messages next to the code.

Give it a try next time.