Stack OverflowCode reading: where can I read great, modern, and well-documented C++ code?
[+47] [13] baol
[2010-04-06 13:46:19]
[ c++ open-source boost code-reading boost-smart-ptr ]

Reading code is one of the best ways to learn new idioms, tricks, and techniques.

Sadly it's very common to find badly written C++ code. Some use C++ as if it was C, others as if it was Java, some just shoot in their feet.

I believe gtkmm [1] is a good example of C++ design, but a binding could not be the best code to read (you need to know the C library behind it).

Boost libraries (at least the one I read) tend to be less readable than I'd like.

Can you mention open source projects (or other projects which source is freely readable) that are good example of readable, modern, well-documented, and auto-contained, C++ code to learn from?

(I believe that one project per answer will be better, and I'd include the motivation that led you to selecting that one.)

EDIT: The question was not intended from a newbie point of view (even if good readings for newbies are welcome, I don't believe that it should make any difference). The reading issue with boost is primarly, as noted in comments, that it's filled with compiler dependent workarounds that make its prose less fluent.

EDIT2: It was not my intention to dismiss all the boost libraries. It's just that trying to read, as an example, the BGL I didn't found the prose I was searching for (even if you can eventually understand them). If you have better examples from boost just point to the specific library.

(1) Depends really on what you want to get from the read. Some of the boost libraries are great pieces of code to read (while others are nearly impossible). Just open a couple of them an try reading... - David Rodríguez - dribeas
(1) I agree with the Boost issue. The problem is that because of portability reasons the code is littered with various compilers work around which greatly alter the readability. - Matthieu M.
Back when I was teaching, I wanted to write "The great American Novel, of code" or at least find it... The idea being that you learned to write [primary natural language] by reading it, so you should learn to program the same way... at least in part... but never got around to it... I still think this is a GREAT idea. - Brian Postow
@david-rodriguez-dribeas can you point us to some of that great pieces of code? - baol
(1) I recommend starting with one for which you know the domain. Else start with the simplests to understand: smart pointers (unique / scoped pointers are the easiest) shared_ptr is interesting (hint: there is no delete in shared_ptr). The problem with reading code is that it will take time until you really understand the importance of details. - David Rodríguez - dribeas
just one word; LLVM - lurscher
[+19] [2010-04-06 14:07:03] Davis King [ACCEPTED]

In my humble opinion I think dlib [1] has some of the most readable code around. Modern style, RAII, no pointers, religious use of contract programming, etc.

But I maybe biased as I run this particular open source project :)


(4) The first paragraph of your homepage fail in its most basic task of informing me about what exactly this library does. - shoosh
(1) Worked fine for me, the meat of it is a bit further down though. - Jamie Keeling
(1) @shoosh: I think it's alright. It is a very general purpose library so it's hard to say exactly what it is about in a single sentence. Although, after looking at it a bit I agree that it can be improved. I just updated it so now it's at least a little better :) - Davis King
[+14] [2010-04-06 13:53:11] Ben Collins

I see that you've already decided that Boost is "less readable than [you'd] like", but Boost is quite possibly the best example of exactly the kind of source code you're looking for. The unfortunate fact is that in spite of all of its positive characteristics, C++ itself is less readable than you'd like.

The more time you spend reading Boost code, the more C++ you'll understand and the more readable it all becomes.

At the op's suggestion, here are some libraries I think are pretty good:

  • smart_ptr - small, pretty self-contained, and idiomatic. Might be a good starting place.
  • pool - more complicated than smart_ptr, but still fairly portable and idiomatic.
  • filesystem - also sort of "medium" complexity, not terribly portable, but very useful and intuitive
  • iostreams - large, complicated, many patterns, lots of platform-specific things
  • asio - also large, complicated, and not portable.

There are many more to choose from.

One of the things that makes Boost good, and still readable, is that most of its libraries consistently factor out the platform/compiler-specific tweaks and leave the primary functionality as portable as possible. It's a really, really great thing for C++ devs to learn.

Note: when I say "portable" or "not portable" above, I'm not talking about the library as a whole, but rather the underlying implementation that a reader would be looking at. In other words, "not portable" means lots of implementation details that are particular to a platform. Boost libraries are amazingly portable in practice; I don't want to be misunderstood.

(13) Reading boost source quickly becomes a lesson in compiler and platform oddities, rather than good C++ idioms. - cpalmer
(6) @cpalmer: actually, it's a good exercise in learning that idioms are not always implemented in their purely abstract forms, and that good design has to take into account platform differences. Call them oddities if you want, but the implementations of the various patterns and idioms in Boost are about the best there are in open-source C++. - Ben Collins
They are good yes, it's quite painful to read them though. I think the problem of compiler support is more an expert topic... - Matthieu M.
(1) Perhaps you could improve your answer giving pointers to one or two boost libraries that are well-suited for reading. - baol
You still "see" and assume to much, but overall I like your answer, thank you. - baol
[+11] [2010-04-06 13:54:37] compie

You could have a look at:

Some projects NOT to learn from:

  • QT [4] ("C-with-classes", not modern C++)
  • wxWidgets [5] (Quite old, has its own string class).

Also I wouldn't recommend reading the Boost code if you are a C++ newbie, you will get buried in little details.


(7) I wouldn't cite Qt as great and modern C++. Qt is more in the C-with-classes category. - Didier Trosset
(7) I wouldn't cite wxWidgets either. No naming convention and contributors doesn't seem to be bound to some kind of coding guidelines. Imho, the lack of rigor makes it a bad project to take lessons from. - ereOn
(1) @ereOn: It also uses a poor string class in a desire to avoid std::string -- a mark of a codebase developed before std::string was considered reliable by many developers. +1 - Billy ONeal
Did not know about Ogre3D, the website seems clean, I've yet to dig in the code :) - Matthieu M.
(2) +1 for both dtrosset and ereOn. Qt is a typical 1990's Smalltalk-like design and wxWidgets is pretty much portable MFC. - Nemanja Trifunovic
(4) I think you are not supposed to overturn the content of your answer :) but I appreciate you can change your mind. - baol
(1) @dtrosset I like Qt, but it does require its own preprocessor, so it can't really be called a good example of C++ code. - rjh
(1) @baol: I disagree. Nothing should stand in the way of improving an answer. - aib
[+7] [2010-04-06 14:25:35] Josh Kelley

I've played around some with Google Test [1] (Google's C++ unit testing framework) and have been impressed with its clean design and clarity of code. It's also interesting to me how Google Test's adherence to the Google C++ Style Guide [2] enhances its readability (even though I don't always agree with the Google C++ Style Guide).

I would expect other notable C++ projects from Google, such as Chromium [3] (the codebase for Google Chrome) and Protocol Buffers [4], to be similarly high quality.


(2) +1 Chromium's code is surprisingly clean and easy to follow for something as complex as a web browser. - ZoogieZork
(1) -1 Burn these C++ google guide: In 4 words: no exceptions, no rtti… why just not to say no C++ - Artyom
(1) @Artyom: I did say that I don't always agree with their guide. :-) Actually, their arguments against RTTI are correct (using it directly really is a code smell), and the guide is pretty clear that they avoid exceptions only because of the difficulty in retrofitting exceptions into existing non-exception-aware code. - Josh Kelley
[+5] [2010-04-06 19:45:27] baol

I'm surprised nobody mentioned Loki [1]


[+3] [2010-04-06 14:08:53] jemfinch

Another well-written C++ project is the Monotone version control system [1].


[+2] [2010-04-06 20:20:28] Artyom

I would say: if the code is beautiful, easy to read, modern, portable and uses latest goodies of C++, then probably you are reading textbook...

Unfortunately most of modern code is not so easy to read and far from being beautiful... Because real life is quite hard.

Examples of greatest modern software libraries that extremely useful and good designed Boost and C++.

  • Boost - includes lots of ifdefs for each broken compiler and to work well on many broken OS platforms.
  • Boost - some libraries push template meta-programming to limit in order to get as much flexibility as possible but readability suffers!
  • Qt - very well designed modern, very useful library (even some people think that if library does not push to limit all templates stuff it is not true C++) but... it requires to run on even very old and odd compilers... So you will find many oddities like not using dynamic_cast or other stuff. But it is great, well debugged high quality software.

Bottom line, programming is hard. Take a look on this code [1] I had written. It is code of cache system with invalidation, triggers, LRU and timeout support, that can be shared between forked processes and normal threads... But it is damn hard to read and understand. But is very valuable piece of software to me that required lots of writing.

(And it is uses STL, smart pointer, allocators, RAII and many other goodies)

P.S.: I do not recommend to learn from my code ;-)


(2) On the contrary, many textbooks have abominably bad code. - Novelocrat
Your code is not bad, I liked reading it. My belief is that good code should also be well documented. In my opinion the hardest and most important programming skill is learning to write good documentation and choose the right names for variables and classes. - baol
[+1] [2010-04-06 13:52:15] shoosh

QT [1] is very well documented and has a nice and elegant design.


(2) I wouldn't cite Qt as great and modern C++. Qt is more in the C-with-classes category. - Didier Trosset
(1) But Qt is a great example of intuitive, easy to use API design. - Barry Wark
(1) @dtrosset Qt is far from being C-with classes, you do not have to push template meta-programming to limits in order to call it modern C++. - Artyom
(1) Qt design is outdated and looks more like Java than C++. Besides, it is still not exception safe: which is unforgivable in year 2010. - Nemanja Trifunovic
QT tries to avoid exceptions because they're not supported on all of the platforms it supports, right? And I'd say QT is fairly well designed and documented. Plus, you have to commend them for their innovative signals/slots paradigm... sure it's an extension and not real C++, but it's an example of elegant and concise design which was followed up by C++ events/delegates. - Nathan Pitman
[+1] [2010-04-06 16:31:18] nos - mostly because it's a complete,complex and large application(s) - and not "just" a library.

I'd learned a lot from the source code of as well.

[+1] [2010-11-26 19:08:17] lurscher

I think one of the projects that i've encountered that definitely deserve praise by the cleanliness of the design and source is LLVM [1]. This library is both very complex, but very modularized, so you probably won't need to learn much about the library that is tangential or unrelated to what you want to achieve. The interesting thing about llvm is that they don't believe that there is a tradeoff between good design and good performance targeting. For example, there are quite a few scenario focused containers implementations [2] that provide optimizations in specific circumstances.

The source and documentation is a pleasure to read, and they take regression testing very seriously.

If someone would like to learn how to design a complex c++ codebase that is mantainable and well designed, is encouraged to study LLVM


[0] [2010-09-28 21:55:01] Kristopher Johnson

I think ACE [1] is a good example of a mature open-source multi-platform C++ library with a lot of available documentation [2]. A lot of the documentation is in the form of academic papers, so you learn a lot about the underlying algorithms, design patterns, and tradeoffs.

However, note that it originated some time ago, and suffers from some ugliness in order to be compatible with all the C++ compilers it has ever supported. So it may not fit your desire for "modern" C++ code.


[0] [2010-11-26 18:08:24] CromTheDestroyer

I've only been out of school for about half a year so this may not mean much, but the Hotspot JVM is the best documented program I have ever worked with (of any language). This includes almost all of the toy programs from university courses with the exception of the OS161 operating system.

Speaking of which, that's another example of great, (very)well-documented C++ code. But it's all C, so it's far from modern.

Hotspot has good documentation throughout, and at every level of abstraction, which is rare. Most of the time programs settle for good commenting, which explains the local details of how code works, but no more. With hotspot, there are plenty of resources describing how the whole thing works, most files have comments saying what goes on in there. So do classes and methods. When certain things are done for optimization purposes, this is noted.

[0] [2012-08-06 18:26:32] Martin Wang

How about OpenSceneGraph? A great rendering engine with very clean structure.