Take the 2-minute tour ×

I don't know if this happens to most Opensource libraries, but many of I know and use (for example OpenSSL, Webkit, ...) they all lack comments, or contain very few comments.

Not to mention their very few documents, it is hard to read their source code. We can hardly understand what a member variable means, or what this function does. This seems to be against coding standard practice

Why is that? How can people collaborate to these opensource with very few comments?

share|improve this question
Not specifically comments are important, but the readability of the code. But I guess you meant that, so you I suggest you rephrase your question. Here was a related question (not a duplicate). programmers.stackexchange.com/questions/185923/… –  Doc Brown Jul 1 '13 at 5:32
In addition to the comment made by @DocBrown above, you want ot make sure that your code is well structured too (e.g. coherent steps in statements). Readable and well-structured code removes the necessity of putting billions of comment lines unnecessarily. And OpenSource projects/libraries are most often for intermediate and advance users of programming/scripting language. If someone just learned to type "Hello World" and goes into those, no comment or code will probably be meaningful to them. Comments are good and necessary, only when you think that it is gonna be ambiguous to a normal user. –  hagubear Jul 1 '13 at 6:30
Note that having few comments does not necessarily mean the code must be hard to read. Ideally, code should be readable without comments. See e.g. programmers.stackexchange.com/questions/1/… –  sleske Jul 1 '13 at 8:22
add comment

3 Answers

up vote 14 down vote accepted

Writing source code is fun.

Writing documentation and commenting code is less fun.

When a developer works in a company which enforces good comments and documentation, there is no choice: either this developer writes those, or he's at risk of being fired.

When a developer contributes to an open source project, he's doing it for free, and especially for fun. There is nobody to force this developer to do things he's not willing to do, like writing documentation and comments.

That's why many open source projects lack extensive documentation and comments.

How people can still contribute to open source projects with no documentation or comments?

  • If the source code is high quality, comments are not needed too much. The comments of public interfaces and the documentation are especially useful for the project consumers, i.e. developers who simply use libraries, not contribute to them.

  • There is no productivity factor involved. I'm working in a company where the actual codebase has no unit tests, no documentation, and no comments. I spend lots of time figuring out what a 600-LOC method is doing or coding things which are already done, but not discoverable because of the lack of documentation, so most of the time, I'm simply wasting company's money instead of doing something valuable.

    On the other hand, for an open source project, it doesn't matter if one of the contributors wasted one week because of the lack of documentation or proper comments. The worst thing which can happen is that this contributor will leave the project.

    Discovering code without comments or documentation may even be challenging, i.e. attract some contributors, instead of discouraging them.

  • In enterprise projects, it is not unusual for a developer to be forced to work on every aspect of a product, and, few years later, having to know nearly the whole system. On an open source project, nobody forces you to know the whole thing. You can simply contribute to a tiny part of it, and have an excellent knowledge of this part, without any need for documentation.

share|improve this answer
"When a developer contributes to an open source project, he's doing it for free, and especially for fun." There are numerous open source projects which people get paid to work with. I doubt the engineers at IBM who work with the Linux kernel do it for free; I think it's a safe bet that the people who developed MySQL were paid to do so; and so on. I'm not saying this is the most common or even particularly common, but it certainly isn't fair either to say that just because the code will be made public the programmer isn't paid to do the work. Customizations even more so. –  Michael Kjörling Jul 1 '13 at 11:09
@MichaelKjörling: +1. Indeed, I've forgotten about this case. By the way, it would be interesting to compare comments in open source code where developers were paid vs. comments in open source code done for free. –  MainMa Jul 1 '13 at 12:36
add comment

Several reasons.

  • Writing documentation isn't fun, and for many projects, the user base is the programming team; everyone knows what the code is about, so documentation isn't really seen as an important aspect of the project.
  • Documentation can (and will) become outdated, and outdated documentation is worse than none at all. This means that documentation is an extra liability, and may impact the flexibility of your codebase (more documentation means for any change you'll have to update the code and the documentation). Especially for very specific open-source projects, this is actually a valid argument to aim for minimal documentation, and write readable code instead.
  • The economics of open source software are different. While it is good to have contributors on your project, many projects are scratch-an-itch type projects which the author has written to solve a particular problem and then just threw out in the open, as-is. Since you're basically eating someone else's breadcrumbs, the attitude is that you are in no position to demand anything, let alone documentation.
share|improve this answer
add comment

How can people collaborate to these opensource with very few comments

Assumed you meant "How can people collaborate to these opensource code which is hard to read" - well, I guess an open source project with bad code will simply have fewer contributors than it could have had with good code. But don't forget that the readability of code lies always in the eye of the beholder, and most open source code is not that bad that you cannot understand at least a a bit or the intentions of some functions and classes.

Often, when you want to contribute something to an open source project, you don't need to understand the whole thing, only the parts where you want to add a specific feature. So if a dev has a need for a missing feature, he will most probably bite the bullet, identify the parts he needs to change, "decode" that parts mentally and add the new features there. If he is a good one, he will also try to review and refactor the "decoded" parts, but I guess in practice this will happen too seldom.

share|improve this answer
hmm, not so sure about bad code meaning fewer contributors. The number of contributors as as much or more to do with the structure and type of the project as with the code contained within it. There's very good code with only one or two people involved, that's intended for a small niche, and bad stuff that has thousands of people plugging away at it with little oversight or oversight by people who themselves are not very good coders (think all those games and stuff that draw schoolkids). –  jwenting Jul 1 '13 at 6:09
I'm in favour of "fewer contributors that it could have had". –  lserni Jul 1 '13 at 6:47
@Iserni: yes, guess I think similar about it, changed my answer accordingly –  Doc Brown Jul 1 '13 at 11:00
I agree with @jwenting . Has someone looked under the hood of Wordpress lately ? –  Radu Murzea Jul 1 '13 at 11:07
add comment

Your Answer


