5

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)

Improve this question
6
  • 1
    What have you found on your own? Where have you looked?
    – Bernard
    Commented Jul 19, 2012 at 13:43
  • I looked through some well known opensource projects documentation without finding what I'm looking for.
    – Geeo
    Commented Jul 19, 2012 at 13:46
  • 2
    @Downvoters: care to comment?
    – Geeo
    Commented Jul 19, 2012 at 14:32
  • My ideology is: If you can draw the logic flow on paper, you can implement it in a system. Software to automate this will take away too much fun IMHO.
    – invert
    Commented Jul 19, 2012 at 14:47
  • 3
    Not exactly what you want, but might be interesting: The Architecture of Open Source Applications
    – CodesInChaos
    Commented Mar 7, 2013 at 11:29

5 Answers 5

Reset to default
1

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.

Improve this answer
2
  • I'm sorry I forgot to mention in my question that I'm most interested in OOP-related design choice (fixed now). Your is a great answer, nonetheless, but I think I will be overwhelmed pretty easily by the Linux kernel :-) Thank you!
    – Geeo
    Commented Jul 19, 2012 at 20:44
  • Interestingly, the linux kernel, though written in C which is technically non-OO, uses an object oriented style in many places.
    – James Kingsbery
    Commented Jul 19, 2012 at 22:10
4

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.
Improve this answer
3
  • would you mind explaining about this in more detail - how and why does it answer the question asked? "Link-only answers" are not quite welcome at Stack Exchange
    – gnat
    Commented Mar 7, 2013 at 14:43
  • 2
    @gnat - if you don't mind, please review my clarifying edit. I think it provides a good example of what we're looking for within P.SE for an answer.
    – user53019
    Commented Mar 7, 2013 at 15:39
  • 2
    @GlenH7 besides wrong spelling of "Eclipse" with lowercase "e", :) I would say your edit is pretty good. Really made me wish to follow the links and learn more about these (as opposed to original answer text)
    – gnat
    Commented Mar 7, 2013 at 15:51
2

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.

Improve this answer
1
  • I'll check it out!
    – Geeo
    Commented Jul 19, 2012 at 20:48
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.

Improve this answer
1
  • I actually work as a software devolper using c# as the main programming language so I will surely get it, thank you!
    – Geeo
    Commented Mar 7, 2013 at 11:14
-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.

Improve this answer
1
  • Yeah, in the context you said, I'm wondering if there is some exceptional well documented code with lot of insight about why the team choose an approach instead of another one etcetc. I tried to look at some code without really finding what I'm looking for. Thank you
    – Geeo
    Commented Jul 19, 2012 at 20:50

Not the answer you're looking for? Browse other questions tagged or ask your own question.