There is a line of thought that says that comments are unnecessary when the code speaks for itself. I don t believe comments would be removed on purpose, though.

I ve seen both sides, and frankly code in general is insufficiently documented.

I ve been congratulated and thanked for leaving copious breadcrumbs but that s because I ve had to sift through too much undocumented code to want to subject anyone else to it.

Call it an ethical obligation.

My reason to document code: my short-term memory is junk. I write comments to remind myself of why I did something. Everyone else benefiting from that is gravy.

I don t think there is a practice or policy to remove comments when releasing software as Open Source. A sneaky software publisher might think that a good idea (maintaining de facto exclusivity, because nobody can t understand it, while having released an open source product) but this would cripple the Open Source project from the start and most likely render it unusable.

The code you are talking about is probably just very little documented. As ocdecio says, that can be either a good sign (the code speaks for itself and does not need comments) or a bad one (it is badly documented, bad code). Both cases are entirely possible. :)

What are you comparing it to?

I doubt that closed-source code has better comments.

As for what functions do, there is probably API documentation. No need to duplicate those in comments.

As a rule, functions should be small enough and written in a way that allows working out how it works by just reading them. A comment on top of the function describing what it does helps getting a quick overview of the function itself when reading through the whole source code file (unless the function name speaks for itself).

Many projects are organized in that way, and that is great.

However, what I am often missing when trying find my way around a larger codebase is something describing the big picture, i.e. the general architecture, principles, what goes where and similar things.

All open source is not made the same. This is what we call a generalization.

If you look at the website Ohloh, which tracks a very large amount of the open source software in existence, it paints a much different picture:

http://www.ohloh.net/languages?query=&sort=code

For instance, in the C language, there are 252+ million lines of comments, approx 1 in every 5 lines of C is a comment. For Java, nearly 1 in 3 lines is a comment. That s not bad.

Open source software has bad comments and bad documentation most of the time. There are various reasons why, some better than others. Usually they relate to laziness or the developers being in the moment . None of the reasons are good reasons.