Emil Sundberg asks:

When serving thousands of customers with Basecamp, Highrise etc there must be a lot of advanced features though, how do you document your projects? How easy is it for a newly hired developer to understand how your products work.

The short answer is that we don’t document our projects. At least not in the traditional sense of writing a tome that exists outside of the code base that somebody new to a project would go read. I haven’t ever seen that work consistently and successfully at any software company I’ve been involved with.

Further more, I don’t really find it necessary for the kind of work that we do. Our biggest product, Basecamp, is about 10,000 lines of code. That really isn’t a whole lot in the grand scheme of things. Everything we do is build is also using Ruby on Rails, which means that most Rails programmers would know their way around our applications straight away. It’s the same conventions and patterns used throughout.

We try to do a fairly good job at keeping our test suites current and exhaustive as well. Basecamp has a 1:1.2 ratio of test code (thanks to the persistence of Jamis!), Highrise has a ratio of 1:0.8 (bad me!). So you can change things in the applications and feel fairly comfortable that you at least haven’t killed the entire application if you make a mistake as the tests would catch that.

Finally, we write our application in a wonderfully expressive and succinct programming language like Ruby that leads itself very well to a programming style like the one Kent Beck preaches in Smalltalk Best Practice Patterns. Keep your methods short and expressive. On average, our models have methods just four lines long. Adding documentation to a method should usually only be done when you’re doing something non-obvious that can’t be rewritten in an obvious way.

Writing documentation for your code base is a very heavy, upfront, planning kind of way to go about things. Maybe that’s what you need some times if you work in an environment that’s especially onerous or if you have very complex policies and strategies you’re implementing. But if you’re not burdened with such things, I’d recommend trying to work on the quality of the code itself and see if you can get by with sparring with new developers.

Got a question for us?

Got a question about design, business, marketing, etc? We’re happy to try to provide some insight into how we’d tackle the problem. Just email svn [at] 37signals dot com with the subject “Ask 37signals”. Thanks.