Please recommend an open source project with quality comments in good english

Question

English is not my mother tongue. However, I have to write comments in english. I want to improve my "comment english" by studying a piece of code which is commented in a good english. Please recommend an open source project which contains a lot of meaningful comments written by people with an excellent command of the language.

Answer 1

I don't think comments are a good place to learn, even if you have to emulate this style. Comments are often not even correct English and good projects will not have too many comments anyway, hence, not much to learn from.

If, on the other hand, you take a project that is commented extensively you can be almost sure that it's not a great role model since the programmers were incapable of conveying terse meaning. This is a generalization, of course. However, I believe it's (almost?) always true. YMMV.

Instead, learn English by studying the experts. There has been a question about this. I recommended “On Writing Well” by William Zinsser and I will do so again.

(By the way, English isn't my mother tongue either.)

Answer 2

I've only ever looked at small pieces of it, but I hear the linux kernel is very well commented.

Answer 3

I've always thought Angband is well commented.

Answer 4

I fairly well commented open source project is Drupal . Check it at Drupal.org . I've developed several portals in it and you can actually learn quite a bit by reading comments in the modules and themes. Actually they are some times more informative then the documentation.

Answer 5

Minix is quite well commented. They can be a bit terse in some places but the comments are very helpful.

Answer 6

Also, if you want to improve your writing... There are a lot of confusing things about the english language. How you master these points is what distinguishes a mediocre writer from an excellent writer. The best, smallest, and most concise book to get (everyone should have a copy!) is called the Elements of Style by Strunk and White. Note that you can get it for 2 bucks on Amazon. Best $2 you'll spend!

Answer 7

I can recommend Simon Tatham's Puzzle Collection.

The comments I've read look like correct English to me. Also, they're clearly written and contain useful information about why things are done the way they are.

The developer documentation is also easy to read and understand, and as a side benefit you'll be reading the documentation of a system with a good and simple architecture.

If you aim to read something and then emulate it without explicitly understanding why doing so is a good idea, I can definitely recommend ST's puzzles. If you want an explicit understanding of what good writing is, I think ST's puzzles will serve as a good example, but you really want to read something like Strunk and White.