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.
Ekerete
on 06 Feb 08It’s been hammered into my psyche that commenting code’s an essential programming practice.
You just upturned that or am i reading this all wrong?
Shawn
on 06 Feb 08@Ekerete I think what David is getting at is that more documentation doesn’t mean better documentation, useless comments add to the confusion. E.g. Don’t comment the obvious.
Wim Leers
on 07 Feb 08Huh?
How about inline documentation, the kind of documentation that you write while you write the code? I use Doxygen in C, C++ and PHP. It seems you can also use it for Ruby.
DHH
on 07 Feb 08Wim, yes there’s RDoc. I just generally don’t use it for projects. When methods are only an average of 4 lines long written in a language like Ruby, it’s often faster and better to merely browse the code base rather than rely on explicit commenting.
That’s not to say that there are no code comments in our code bases. Just very little. And usually only to describe something that looks like it shouldn’t be the way that it is. Something counterintuative.
Short of that, I consider documentation for high-level stuff to usually be a cop-out for poor programming design.
Note, this is quite different from, say, a reusable framework that’s comparably “close to the metal”. For that kind of stuff, inline code documentation usually makes a ton of sense and should be used extensively.
Anson
on 07 Feb 08I pretty much agree with keeping documentation light but I think this concept of “is this code readable without comments” often misses an important point of commenting code.
It’s not that you need explanation of what you wrote, but why you wrote it that way.
Often there are numerous solutions to a problem and when you go back to extend some old code you have to kind of “re-solve” the problem to get back into the mindset of the solution you came up with. This can be quite time consuming - this is, going through and eliminating the alternate solutions - and this is often where I wish I’d captured those scribblings and quick diagrams in the form of a paragraph or two.
So I guess it’s about documenting process rather than output.
sandofsky
on 07 Feb 08I only comment to warn developers. Sometimes the code has to be ugly for performance reasons, so we need to warn not to refactor it. Sometimes logic has to be convoluted for edge cases or business requirements, and a comment “Don’t try to figure this out,” will save a developer time.
Dustin Senos
on 07 Feb 08One method for commenting that I try to enforce upon myself (it’s harder then it sounds) is only writing a comment when I can use the word “because” ie:
// Loop through our array backwards because it’s more clear to the user to display the last item first
vs:
// Loop through our array backwards to display the last item first
It doesn’t work everywhere, but when you come back six months down the road at least you have stated your reasoning, not just the obvious.
Weixi Yen
on 07 Feb 08What about project documentation? How are you all able to stay on the same page as to the exact business requirements of Basecamp?
Do you just code it how you want, and make changes as people catch them, or do you all agree on what you want first and then begin coding?
JohnO
on 07 Feb 08So lets take it out of the application, and down to the framework. I’ve see the Rails API, it is just as unfriendly as the rest of code documentation on frameworks and languages. How would you improve upon that?
pwb
on 07 Feb 08I wonder if you guys have any representative code that you wouldn’t mind sharing?
Keru
on 07 Feb 08David, I’m waiting for your reaction to the recent git hype.
andycamp
on 07 Feb 08Comments lie. Code tells the truth. I’ve been burnt by bad comments far more than by bad code.
Baz
on 07 Feb 08@dustin yeah – with Ruby code it’s pretty easy to figure out WHAT the code is doing and HOW (well usually, anyway).
What’s more important is WHY (hence your “because” requirements) and WHERE does it fit in the grand scheme of things (which tends to come out of a conversation between the people involved). For me, this tends to happen over IM and in Basecamp message threads. I would guess 37s uses Campfire for this?
Webmonkey-in-Ireland
on 07 Feb 08I’m not a Ruby programmer, (.NET), but I do agree with writing code that doesn’t need commenting. A developers goal should always to write self documenting code, regardless of platform. However there are always going to be times when you need to remind yourself (or other developers) why something was done a certain way.
matt
on 07 Feb 08@DHH:
“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!).” David, 1:0.8 isn’t bad. What’s important about the test code is the coverage. If you’re 1:10 or 1:0.1, it doesn’t matter as long as your coverage increases. Well..technically the less test code with higher coverage the better…but I think you get the point.
Saverio M.
on 07 Feb 08I don’t agree with the post given its generality.
Given a 10k lines project with 4 lines methods and a single level of inheritance, which is small, I agree.
But there are several issues that code can’t express, which are move evident in different kind of projects.
Code doesn’t express the rules of interaction with client objects. It doesn’t necessarily express processes, or the possible tricky passages, like algorithms. It doesn’t express specific reasons (like pointed by Anson) for the choices.
It’s obvious that code “could” but a comment in this cases it’s much more immediate. Also, code must be, at least in some extent, decoded, while comments don’t.
Hey wait a moment, why don’t we write a CS book in ruby? It’s sooooo expressive, that we don’t need the author’s comments ;-)
Peter B.
on 07 Feb 08Steve Erickson
on 07 Feb 08Thanks for the post DHH. Although, what you’ve written seems to be limited to what I would call “unit” documentation; that is, documenting little, individual chunks of code. Do you guys do any kind of “integration” documentation. Maybe something like documenting the order in which some chain of methods get called? Or in the case of Rails, the lifecycle of a request and how it moves through the dispatch code? What are your thoughts on that type of higher level documentation?
Justin
on 07 Feb 08I’m of this school too. Elegant code should be self-describing, and if you need to explain some perverse logic it can probabloy be rewritten. I rarely document my apps much more than a small descriptive block before the method. For everything else if someone can’t pick up the code from simply looking at it then we probably failed in our hiring.
Charlton
on 07 Feb 08It’s been my experience that if you pick good names for things and put in a comment every time you do something in a non-obvious way or make something simple but wrong complex and right, you’ve got almost all the documentation you practically need.
This is admittedly not what most people, used to the paper-pushing bureaucratic method of software design, would consider documentation, but it’s documentation nonetheless.
What I’ve found in practice is that lots of documentation about why things work the way they do, in particular with lots of documentation about conventions, is invaluable when learning. I could not have picked up Cocoa, for instance, by just sitting down and starting to code; there are some fundamental assumptions and fundamental approaches, among them things like the conventions of memory management, the particular approach to MVC, the notions of key-value coding and key-value observing, that just need to be explained.
But this is a difference probably closer to DHH’s idea of how a reusable framework should be documented as opposed to how an application should be documented. Because I’ve read and followed the Cocoa approaches, my Cocoa applications can get by with a lot less documentation.
John
on 07 Feb 08@matt:
I think that’s a fine idea. If I’m studying someone’s algorithm, I want to see it in code, not some high level english representation.
Chris
on 07 Feb 08If I ever saw the comment “Don’t Try To Figure This Out” I would just assume it was some nasty hillbilly code. And I’m pretty sure I’d be correct.
Tom G
on 07 Feb 08I have yet to meet a productive programmer who like writing documentation.
Comments in source code are not the same thing as documentation however…
Dustin Senos
on 07 Feb 08While reading the comments I couldn’t help but ask myself:
Why not comment?
If you code is clean enough to read like a story then you would need to comment less. I think striving to write code which is easy to follow without comments is a respectable goal, but when it comes down to it, what’s the harm?
Chances are someone else is going to look at your code down the road, they will thank you for describing why you came to the solution you did. And when they have a question for you, you will thank yourself too.
We need to focus on how to write comments. Once we master that, it will be obvious where, why and how often to comment.
Evan
on 07 Feb 08If you want to “get real” – I think commenting should be driven by the code’s actual needs, and not by some philosophy of what it should need.
I can’t say it better than Dustin:
Evan
on 07 Feb 08To spam it up a little more:
It’s not that you shouldn’t be able to understand code without comments. It’s that a well-placed and well-written comment helps you understand it faster and better.
Saverio M.
on 07 Feb 08@John
By chance, I am really doing it. I’ll post my specific opinion on the site however; here it would be quite off-topic.
BradM
on 07 Feb 08@DHH
I like your comments concerning your test coverage. I usually wouldn’t ask such a question on a 37S board, but since it has been brought up…
Are there any new or old Rails/Ruby books that you might recommend for strictly testing purposes?
Tom G
on 07 Feb 08As is the case in many things in life, there are no hard and fast rules – common sense should dictate documentation and commenting.
There is nothing I as a programmer hate more than spending hours, tracing through somebody’s obtuse spaghetti code to figure something simple out.
Sometimes it helps greatly to have the big picture. Sometimes there are complex business rules that need a brief explanation.
I only comment when necessary, but they are often necessary.
To say that you write in “insert programming laguage here” and that it is a self documenting language is a bullshit excuse for lazy programmers. Maybe if you’re whipping out a trivial piece of scripting code that has the shelf life of a banana, who really cares.
The golden rule of commenting applies: put yourself in the next person’s place – if you would have liked an explanation in their place – explain yourself.
DHH
on 07 Feb 08The need for commenting does change depending on your average code base size. There’s a very different need in a code base of 100K lines and one of 10K.
Also, if you’re hunting through “spaghetti code”, why do you think that the person who wrote that would be capable of writing good documentation? Spaghetti code is sloppy thinking, sloppy thinkers does usually not make great writers.
matt
on 08 Feb 08@DHH:
“sloppy thinkers does usually not make great writers”
Nor do tired thinkers evidently ;)
Howard Fore
on 08 Feb 08You need documentation outside the code and comments in the code because it is often easier to understand what someone is doing in the code when you already understand what they are attempting to accomplish. If someone just throws a chunk of code at someone who’s unfamiliar with the object then you’ve got to spend a lot of processes reverse-engineering the code in your head, figuring out not only how it does something but what that something is. If you already have a grasp of the objective then it is often much easier to follow along, as well as find places where you may have done things differently.
idontRemember.it
on 08 Feb 08I never saw any comment in complicated database queries (Inside the query).
This would save a lot of time….
Ben
on 12 Feb 08It all kind of depends on what you are doing. For expressive high level stuff in ruby the code can generally stand for itself and comments just get in the way. For really math heavy number crunching, things like Doxygen’s embedded LaTeX in comments is crucial. Even math code that is more expressive and detailed in code often benefits from the actual mathematical formatting because it allows other people to relate it back to other formulas or equations they have seen. It’s kind of odd to have some code bases with 20% of the lines being comments and then have another project with like 5 lines throughout.
This discussion is closed.