As I’m trying to get better at designing good software I’m wondering if there are out there good (as in well written) open source software with lot of code documentation that aims to explain details about why this or that design choice was made in the context of that specific problem set. I’m interested in OOP and I don’t really care much about the language (php / java / c# are preferred tho :))
Example:
Problem: X
Possible way to handle this problem: A, B, C.
We choose B because… (technical details about the implementation, pros and cons, code comments etc)
6
One good example is the Linux kernel. The mailing list explains many design decisions, and there are also books that describe why the internals are written the way they are (one example being Understanding the Linux Kernel, although it looks like there are many others. Linux Magazine also has (or at least used to have) a summary of the mailing list talking about the main discussions/design decisions in the kernel community.
EDIT:
Since the kernel can be intimidating to just start “learning,” here are a few areas to start with:
- Task scheduling
- Kernel memory allocation
- file system
If you limit the scope to a single component, it should be easier to understand.
Also, to look at the code easily while reading documentation, it might help to look at LXR.
2
These books offer some high-level perspective on how and why certain open-source software is designed the way it is:
The Architecture of Open Source Applications
There are two volumes that cover a wide variety of open-source projects, both old and new. For example:
- The article on bash covers a number of decision points and even has a section near the end about “What I would have done differently” to provide a retrospective.
- The article on Eclipse provides several diagrams, code snippets, and discusses some of the evolution through the various major versions it has been released under.
3
The book Beautiful Code documents design problems and their solutions. I don’t remember if all the chapters address open source projects, but at least one of them (the chapter on a particular design problem in SVN) does.
1
I would advice reading two books.
For me this first one is THE BEST BOOK ON PROGRAMMING EVER! 🙂 (And it doesn’t matter if you don’t use C#, you can still read it)
Agile Principles, Patterns, and Practices in C#
Clean Code
I really think first one should be read by every programmer.
Edit:
Those books are great resource for people that are trying to get better at designing good software. People looking for good (as in well written) open source software/code examples with lot of code documentation that aims to explain details about why this or that design choice was made in the context of that specific problem set.
Plus it has big section on organizing your assemblies. I haven’t seen this in any programming book. And I have read probably 30.
1
There’s a massive amount of code available for Java system classes. It probably lacks the level of documentation you want, but it’s real code solving real problems. If you work in Java anyway it can be easy to get at and real interesting.
1