Fog Creek Software
Discussion Board




Linus on Open Source documentation

In a recent <a href = "http://www.kerneltraffic.org/kernel-traffic/kt20030509_215.html#3">LKML</a> thread, Linus Torvalds gave some of his thoughts on documenting code in Open Source projects:

"Some people care about documentation, some people don't. That's a fact, and spouting platitudes about "improving their work" just doesn't _matter_. The whole open source idea is that people do what they care about and what they are good at, and exactly because they aren't forced to deal with issues they don't have a heart for they take more pride and interest in the stuff they _do_ do.

Personally, I don't write documentation. I don't much even write comments in my code. My personal feeling is that as long as functions are small and readable (and logical), and global variables have good names, that's all I need to do. Others - who do care about comments and docs - can do that part.

And you know what? That _lack_ of comments and documantation improves my work. Not because documentation is bad, but because I DO NOT CARE. So I concentrate on the stuff I do care about."

Comments?  Is this true in the non-open source world as well (or even true at all?)  My first thought was that leaving out documentation may improve the coder's work, but it probably leaves more work for the maintenance programmer or other coders on the team.

John Wilson (www.jowilson.org)
Friday, May 09, 2003

Fixed link:  http://www.kerneltraffic.org/kernel-traffic/kt20030509_215.html#3

John Wilson
Friday, May 09, 2003

It depends on the nature of the maintanence. If you got a maintanence contractor or coder who lives with the code for a year or more, he'll handle just fine (plus some hand-holding). But if he is expected to write a new component that must depend on knowledge of the rest of the system (lots of magic values and dependancies) and he's got to do it NOW! Then you'll run into some problems that could be eliminated or reduced with good documention.

It also depends on the nature of the maintanence. Is he expected to make major upgrades? Architectual changes forcing a lot of rewrites? How bad is the code base? Is it spagetti code you are maintaining or loosely coupled components by the thousands and each is separate and distinct?

Li-fan Chen
Saturday, May 10, 2003

I agree.  The codgy old bastard that took me under his wing when I was fresh out of school always said "The code IS the documentation!"

       
Saturday, May 10, 2003

For some people who say "the code is the documentation" it is just and excuse for laziness and dicking over anyone who has to work with your code in the future.  For others it might be mostly true, especially if you give highly descriptive (and often long) variable names.

For the average coder there is actually a perverse incentive not to comment.  It makes coding take longer and makes it easier for them to be fired because it is easier for others to maintain their code.

Erik Lickerman
Saturday, May 10, 2003

I equate proper (useful) code comments to a level of professional discipline.

Mitch & Murray (from downtown)
Saturday, May 10, 2003

And the reason open source is not taken seriously is...

oc
Saturday, May 10, 2003

To the question is it an "open source issue?" No it is not.  It is a source issue.  You will find undocumented garbage code at MS.  You will find it at any fortune 5000 company and probably just about anywhere if you look.  It is not the deciding factor of Open Source. Frankly, you have not idea whether the next piece of proprietary software you buy is documented at all.  Whether it was developed by extreme programming, OOD, or 2000 contractors with only the knowledge of what they were told to change.  If you think otherwise, you are kidding yourself.

If it is not a requirement of your workplace, by which I mean it is reviewed and if inadequate or missing will not get loaded, then this will happen.  It will be the new developer or the one making a production fix that needs to get out there now, and they promise to update the documentation later.

Is it laziness? To a certain extent, although people will argue the priority of doing so given "X" minutes in a day.  If documentation is less important than getting one more change done, documentation will slip.  After a few iterations of this, it is likely that they end result is code, whose documentation you cannot trust.  So is that worse?

Mike Gamerland
Saturday, May 10, 2003

That proper code comment habits and general documentation is even debated here strikes me as amazing.  I mean I am blown away by any argument against or rationalizing no/poor code comments and docs.

There is no excuse for not doing it / insisting on it.  Period.

Oh yeah, and the Linus Meister just went down about twenty notches in my book based on his comments on the subject.  What a dumbass. 

David Cutler - you are still safe in your role as the senior Grand Poobah in the OS Development Derby.  I've seen some of the BLISS VMS source, and it is just _fine_. Sorry to see you don't seem to be running Formula Atlantic this year.

Mitch & Murray (from downtown)
Saturday, May 10, 2003

Good documentation tells you stuff that you don't know when you're looking at the code.

Code can tell you what program has been written, and how it works. This is important to know.

Code can't tell you why you didn't write the program another way, or why you didn't write a completely different program to start with. These things can actually be important too.

Personally, I figure that if you can explain what you're doing to another person in 5 minutes, writing it down so that other people can refer to it later on shouldn't take more than 10 minutes, even if you're a slow typist. However, if you do have a willing person available, it's perfectly reaonable for them to do the typing, as long as you make sure they had an accurate understanding of what they're writing about.

I suspect Linus does a fair amount of talking about Linux, and while it's practically required for someone to summarise the decisions for the benefit of other coders, there's no moral requirement why he should be made to do that himself, especially if someone more interested and able to do it is available.

If anything, most coders need a competent technical writer to do their documentation.  :)

andrew m
Sunday, May 11, 2003

"...the Linus Meister just went down about twenty notches in my book ..." 

I'm sure he cares.

Nat Ersoz
Sunday, May 11, 2003

I'm developing the same program that I started working on 3 years ago, about half of which I have written.  It's complex enough that my comments from 3 years ago are still useful in shortening the update-correction coding.  My younger self is speaking to my older self and helping it out.  Thank you ME!  I'm commenting now for my future self, who will have forgotten the point of an algorithm, a reason why an "obvious" change will break another part of the program and a special feature of the language that really helps to do what I want done.

Barry Sperling
Sunday, May 11, 2003

Andrew M.:  Yeah, I can see that.  One could almost say that the linux kernel mailing list serves as a repository for the type of documentation you're talking about.  ;)

The more I think about it, the more I come to the conclusion that not everyone can be Linus.  Maybe Linus can just omit documentation and commenting in large projects, but us mere mortals don't have that luxury.  But he's also right in a certain sense.  Switching from writing good code to writing good english documentation is a task switch, at least for me it is.  The two tasks use different parts of my brain. 

To get back to what Andrew was saying, one way of looking at it is that there's benefits and disadvantages to tightly coupling the source code to the documentation.  Benefits are that that the documentation is right there in the same file as the source.  Being right in front of your face, the red block of text (or whatever color comments are in your editor of choice) makes it easier to pay attention to before you make that "obvious" obvious change.

But there's quite a few disadvantages as well.  I mentioned the documentation task-switch earlier.  The effect of this is that it becomes un-motivating to switch from changing code to changing the documentation that sits right above the code. 

Something I've found recently that helps is to keep a seperate "documentation tree", in fact, the first file I open on any project now is documentation.txt, which contains an overview of the whole project (usually I base this on a sheaf of paper notes).  Then as I write code, usually after I finish a function, or major component, I flip over to the documentation window and write an english description of the function or module or whatever.  On small projects, everything fits into documentation.txt, larger ones get a documentation directory and seperate files.  Having two seperate editor windows helps keep the task switch explicit (and actually makes it more fun, because I like writing english and I like writing code).

Of course, I still comment my code with brief summaries of functions and explanations of tricky sections, usually with a tag that says "for a detailed explanation, see such and such in the documentation file." 

John Wilson
Sunday, May 11, 2003

"That _lack_ of comments and documentation improves my work."

This coming from a man who thinks debuggers are evil because problems will always be better analyzed by reading printf() output. 'Nuff said.

But then again, if the code is the documentation, then all the code will be bug-free, because it will always be in accordance with the specification, by defininition!

Roland Kaufmann
Sunday, May 11, 2003

My first interview question is "Do you consider the code to be the documentation"?

I'm finding that 70% of my interviews are only one question long....

Marc
Monday, May 12, 2003

The equivalent would be saying "the engine is the documentation" to a mechanic. Sure he can figure it out but wouldn't it be wiser to give him some documentation?


"That _lack_ of comments and documentation improves my work."

Uh, that's because you wrote it.

Ian Stallings
Monday, May 12, 2003

Ian: Which, I think, is exactly the point.

Linus is writing about a specific situation:  open-source code that he wrote and is intimately familiar with.  It's not fair to assume he believes the same thing about all code in all situations.

Are comments useful?  Yes.  Can comments be overused to the point where they obfuscate development?  Yes.

The sweet spot is to develop only as many comments as you need.  The perennial difficulty lies in figuring out exactly what that is.

Are you developing code that only you will ever touch?  Then maybe you don't need any comments.  Are you working on a massively distributed system that will be "thrown over the wall" to maintenance programmers in six months?  Then you'd better comment at least the tricky stuff.  Are you writing an API?  They you'd better comment every function.  Are you in a different situation?  Then your answer will be different.

Brent P. Newhall
Monday, May 12, 2003

You sirs, are all morons. Comments never help.

Mr Bloh
Tuesday, May 13, 2003

And if Linus gets hit by a bus this morning?

The only code only you will ever touch is the code that only you will ever run.

Marc
Tuesday, May 13, 2003

It's just that Linus serves as one of a "Guru to Open Source development and others in the same field take his comments as if they were spoken by god himself. So they see him saying comments are useless in his particular case, kernel development, and do the same across every application. Look inside any open source application and you'll find a //HACK //KLUDGE of //TODOs and lack of anything useful. Although this is a broad swipe my point is this - wouldn't comments be more useful to Open Source then any other kind of software? I mean you know someone will read it right? Why be lazy? Are comments really getting in the way so much that you can justify leaving thousands (or millions in the case of Linux) without any reference but the code? It just seems very short sighted. I know it could be justified but I just choose to disagree.

Ian Stallings
Tuesday, May 13, 2003

I just took Linus' thoughts to heart, and developed a few emacs utils for a Windows-using friend of mine.who wants a little more power early on in the learning curve.  I decided not to document as much as I normally do.  I felt a lot freer to change code and add features because there's one less thing to sync with.  I did annotate code that newbies might not understand, and felt I had time to write other (non-code) documentation.

I'm glad he wrote this because documentation isn't a cut & dried case.  People rarely talk about programming in the small, as opposed to sweeping strategy.

anonymous emacser
Tuesday, May 13, 2003

Regarding the "If Linus gets hit by a bus" argument:  Does all software have to be that robust?  Do you think that that thought never crossed Linus' mind?  What if he's willing to accept that risk?

Or:  If someone paid you to write a macro in fifteen minutes, and you wouldn't have time to develop it *and* comment it, would you refuse the job?

Brent P. Newhall
Tuesday, May 13, 2003

What if HE is willing to take that risk? Screw him! I'm the one taking the risk! He gets hit by a bus and suddenly this OS (that I likely bet a lot of my company on) is lost.

Of course, this is always a risk with Open Source (that the key figure will leave and the project will die). It is one of the main reasons I avoid it under most circumstances. I don't trust in a groups passion for the product (open source) nearly as much as I trust a groups passion for financial gain (commercial software).

Marc
Wednesday, May 14, 2003

[You sirs, are all morons. Comments never help.

]

This one certainly doesn't......

Nev
Sunday, May 18, 2003

*  Recent Topics

*  Fog Creek Home