19

Part of the value of Open Source is to provide great example code to people getting started with a new platform or language.

What's the best Open Source code you've encountered, and why do you like your choice? Any language will do, but I'm particularly interested in the best examples of Objective-C you can point out.

Obviously this is an open-ended question, so I'll leave the question open for a while and see what kinds of answers we get.

Thanks!

EDIT: For "best" I was thinking of code that follows the idioms in the given language or platform, as well as including the parts that make code "professional" - good documentation, a testing suite, etc. Code that is concise, but not overly clever is preferred to very terse or chatty code.

Andrew Theken
  • 310
  • 4
    Any particular definition of "best" in mind? –  Jan 01 '11 at 17:25
  • Your question is a bit broad. Perhaps you can edit it to be more specific and define what "best" means to you. Best UI, best desktop/web/phone app, best concurancy, best visually appealing code? – Walter Jan 01 '11 at 18:05
  • +1 for a good question. I suggest you prune it to some specific language/technology. Comparing C for Linux vs Java for database driver is frankly an inconsistent idea. – Fanatic23 Jan 02 '11 at 04:36
  • It would be very helpful to others reading the question if you edited that clarification into it. :) – Michael K Jan 03 '11 at 15:10

11 Answers11

14

I have to say that having looked at bits of open source code over the years, I've been hugely disappointed with pretty much all of it.

The main irritation for me is that there are usually very few comments, frequently the only comments are some long and legalistic copyright notice.

The linux kernel is an example where the files frequently don't even have a comment in them saying what purpose they serve (eg driver for XYZ would at least tell me I'm in roughly the right place).

I've come from commercial and defence programming where the coding standards require sensible intelligible comments not just to say what a code unit does, but through out the code there must be blocks of comments that describe algorithms, methods, peculiarities, hacks / clever things, all so that whoever comes after can look and figure out QUICKLY what is being done rather than by painstakingly wading through the actual code.

Perhaps the moral is: Tell me what you are doing, dont make me figure it out.

I've not found ANY open source code that does this well. As far as looking to open source as a means of learning good coding practices, my jaundiced advice is: Don't.

quickly_now
  • 14,942
  • I agree that open source projects are often poorly commented and poorly documented. But they are all volunteers. It's hard to motivate volunteers to do unpleasant things usually without the reward they are looking for (status, social, achieving great things or doing what they love). –  Jan 02 '11 at 12:47
  • @pierre303 - I founded and maintain NoRMproject.org, One of the main things that I do is to write comments when I write the code, and this helps. I think that contributors will work on the parts that the leaders emphasize. In the case of NoRM, that was Tests, Comments, and Idiomatic (to c#) code. I think we have a pretty professional, maintainable codebase because of it. – Andrew Theken Jan 03 '11 at 00:55
  • I agree that comments should be written as the code is being written. (I also do this in all my own code, mainly because I'm selfish and it helps me to write a narrative before the block of code - it clarifies in my own mind what I need to do before I actually do it.) – quickly_now Jan 03 '11 at 01:14
  • Reminds me of this funny quote I once bumped into: "If I had a hard time writing it, they should have a hard time reading it." – Denis de Bernardy May 25 '11 at 10:16
  • +1, @quickly_now - you think that code should be well planned, well tested and now well commented! What kind of crazy planet are you living on? –  May 25 '11 at 11:28
  • Good code should be selfexplaining (Methodnames, Propertynames etc), so that you don't need comments to read the code. So instead on focusing on comments focus on good code. – Tokk May 25 '11 at 14:28
  • Sorry Tokk - that kind of thing does not actually work very well in practice. Wait till you write some code implementing signal processing algorithm on a microcontroller with 32K of memory, and you can only use plain C. – quickly_now May 25 '11 at 23:38
  • @Cow: Yeah, I know, fantasy land. – quickly_now May 25 '11 at 23:39
5

I have heard very good things about the Sqlite codebase.

From the little I had looked into it, it looks very clean.

Oded
  • 53,586
  • 19
  • 167
  • 181
5

Donald Knuth wrote two programs to help him typeset his mathematical formulas in his books better than his publisher could.

These two programs (in their final version) was written using Literate Programming which allowed for creating a printed, typeset version of the source code, and they were published as books. These are simply the best documented programs I've ever read!

  • "Computers & Typesetting, Volume B: TeX: The Program"
  • "Computers & Typesetting, Volume D: Metafont: The Program"

They are not available for online reading, but Amazon allows you too "Look inside" the Metafont book at http://www.amazon.com/Computers-Typesetting-D-Metafont-Program/dp/0201134381/

Warning: It is heavy stuff, which is why each book runs at 600 pages.

  • 1
    Note: It is the typeset version that isn't available online. The source is fully available, and can - with a small effort- be used to generate the printed version. –  Jan 03 '11 at 17:06
4

The book Beautiful Code tries to answer this question with several samples of what the contributors think are exemplars of beautiful code from open source projects.
alt text

Tangurena
  • 13,304
4

CodeIgniter

Some of the cleanest, best documented source code I've seen from an OS project.

Josh K
  • 23,029
  • 1
    php & cleanest? – Kugel Jan 08 '11 at 18:44
  • 1
    @Kugel: Yes to both. – Josh K Jan 09 '11 at 02:31
  • Just had a look at the source to CodeIgniter, and it does indeed seem very well structured and clean. I think as beautiful at you can get in php. :) And I always liked humor in source code: "// No DB specified yet? Beat them senseless... if ( ! isset($params['dbdriver']) ..." – Bjarke Freund-Hansen Jan 10 '11 at 08:27
  • I've recently started working with CodeIgniter, so far I've been rather pleased. – Ben L Jan 10 '11 at 15:31
  • 2
    I had a peek at the source code and I must admit it was well documented and easy to follow, and I did not expect it from a OS PHP. – OnesimusUnbound May 25 '11 at 10:21
  • 2
    Another great OS PHP framework is fuelphp (http://fuelphp.com/) which is also documented, laid out cleanly and uses naming conventions that don't make you pull your hair out. That just proves it's not PHP to blame for spaghetti code, it's usually the people writing the code. – Michael J.V. May 25 '11 at 11:51
  • Just had a look at the code, and coming more from a C# background, this is some very well commented code. Almost makes me want to use PHP (: – DMan Jun 15 '11 at 03:11
3

I have seen 2 projects that are very well structured:

  1. Django
  2. Chromium project

Especially, second one is very interesting based on few things:

  • How it uses processes for many things (tabs, plug-ins) and how it fits together
  • multi-platform with native GUI for each Windows, Mac, Linux
  • web-kit integration

Also I heard Postgre is written cleanly (as opposed to MySql), but I haven't read it myself.

Kugel
  • 789
2

Some say the C code for the Linux Kernel is pretty darn good.

(Not that I understand the thing! It's possibly the best written open-source C project around.)

Noldorin
  • 136
  • 1
    For optimized code it's great. For readability not so good, in my experience. Of course, I haven't written any, just read it... – Michael K Jan 03 '11 at 15:11
  • 1
    Yeah, true. Unfortunately the question did not really define "best", so I'm taking my own definition. :) – Noldorin Jan 03 '11 at 16:04
2

I've found the LLVM source code to be very readable. I'm pretty sure it's the cleanest C++ I've seen. If you're not familiar with it, it's basically a compiler construction toolkit.

  • It has an extensive test suite. Well actually, it has at least two: one set for testing features and one for testing performance (of LLVM itself as well as the compiled programs it generates).
  • The code is well-commented.
  • Highly repetitive code (such as the instruction matching in the various backends) is auto-generated from a higher-level DSL (called TableGen) description.
    • This also allows multiple disjoint pieces of code to be generated from the same description. For instance, the backend specification is used as part of a compiler backend, but also for assemblers and disassemblers.
  • It has pretty good documentation.

It's a pretty big project though, so don't expect to be able to quickly understand exactly how everything works. But it should be pretty easy to get a high-level overview.

Frits
  • 769
1

It's not a huge project, but the SubSonic ORM was extremely easy for me to hack. It was the first real open source project I was able to modify exactly how I needed. Most of the others I ended up looking at the source and banging my head on a wall. I had it partially supporting PostgreSQL (basing it on the SQL Server provider thing) within a few hours. It's the most well organized project I've seen yet... though not to say I've looked at a lot of open source projects.

Earlz
  • 22,848
0

First a simple example: The code for the event handling system zope.event. I'd used other event systems, which dispatched events to different event listeners. When I saw the zope.event code it was facepalm time, when I realized how simple some things could be.

It's written in Python, and here is the code in it's entirety:

subscribers = []

def notify(event):
    """ Notify all subscribers of ``event``.
    """
    for subscriber in subscribers:
        subscriber(event)

To add a subscriber you do this:

from zope.event import subscribers
subscribers.add(MySubscriber())

The best example of KISS I've seen.

Then a more complex example: The Martian code base is very nice and easy to read, even though it's using some clever Python hacks. The same goes for most code of Grok, which is built using Martian.

Lennart Regebro
  • 2,275
  • 3
    I don't understand what is great with this code. I don't know python, but I can only see a simple use of the observer pattern here, and nothing else. – barjak Jan 02 '11 at 18:06
  • Have you compared it with other event systems? For simplicity take another Python example: http://pypi.python.org/pypi/pyjon.events/1.1.1 – Lennart Regebro Jan 02 '11 at 18:38
  • 1
    Beautiful - I actually wrote something very similiar in javascript. I guess I'm smart? ;) – Michael K Jan 03 '11 at 15:13
  • Just because there's event systems that are far worse, doesn't mean this is great code. I saw exactly this code in tons of languages. And more importantly, I saw type safe implementations. – back2dos May 25 '11 at 11:00
  • @back2dos: This is type safe. – Lennart Regebro May 25 '11 at 11:05
  • @Lennart Regebro: Yes, sorry, I wasn't specific. You could argue, that strongly dynamically typed languages provide type safety. What I meant was: statically type safe. I want to see errors occur before I call notify. – back2dos May 25 '11 at 11:38
  • @Lennart Regebro: That was exactly my point. You can have it as short as that, and yet typesafe. The point of such things as static type systems is to convey information to a static analyzer, that can then automatically determine semantic integrity before execution. There's a number of languages, where both is feasible, such as haXe: var subscribers:List<Event->Void> = []; function notify(event) { for (subscriber in subscribers) subscriber(event); }. This code is typesafe and just as simple. – back2dos May 25 '11 at 13:41
  • @back2dos: So all you say is "I like this, but I want to use a static language". Well, so use a static language, then!? Or are you saying "I have seen this but importantly in a static language"? How is that important? I get the feeling all you are trying to do is to complain that's it is Python??? – Lennart Regebro May 25 '11 at 13:46
  • @Lennart Regebro: What I am say is "I have seen this, but a variant, that is not only just as simple, but also type safe". The question is "What's the best open source code you've ever seen?". My point is, that this is not particularly good and I have seen better. – back2dos May 25 '11 at 13:55
  • @back2dos: I repeat: This is type safe. What you are saying is "I have seen this also in a statically typed language". Yeah? So? What is your point? If you are trying to imply that static languages are better, then you are wrong. – Lennart Regebro May 25 '11 at 14:03
0

Consider reading this book The Architecture of Open Source Applications. It should give you a critique of why and how the design decisions were made in the projects that are discussed in the book.

Instead of looking for the best, which can elude you for long, try and appreciate the design of some projects, perhaps beyond the scope of the book. That could help you build up on the successes of these projects instead of repeating their mistakes (or, as popularly called, reinventing the wheel).

vpit3833
  • 1,320