Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I want to improve my programming skills by studying famous open source projects, but I find it is easy to get lost by just jumping into their source code.

So I decided to read their documentation about their design or architecture (such as UML diagrams) to get a general idea about their code's organization first. To my surprise, however, I can't find any architectural documentation for large open source projects such as Hibernate, Spring, ASP.NET MVC, Rails, etc.

So I've started to wonder: How can an open source project can be successful if new-comer developers have no architectural/design documentation to read, or if the project manager just opened the source code but closed its documentation?

share|improve this question
3  
"most"? Can you back this up with concrete statistics? How many did you read? How many are there? How many lacked appropriate documentation? If you don't have numbers, please remove words like "most" and replace them with real facts based on what you really found. Also, please capitalize "I" when referring to yourself. –  S.Lott Jun 29 '11 at 10:13
    
@S.Lott Sorry for the subjective "most". I am a newbie in software industry. I do trying to search for documents which I had heard of during college school(such as UML Diagram,Flow Chart,Brief Design Doc,Detaled Design Doc,etc) for the mentioned projects both at their project website or code repository but without luck,only to find some user-guide doc. Can you please teach me some common way to search their desgin/archiecture documents? –  TomCaps Jun 29 '11 at 10:32
1  
Please remove "Many". That's just as incorrect as most. please update the question to specifically list the specific open source projects that specifically lack the specific documentation you want to see. Please be precise and specific. Please do not be subjective and vague. –  S.Lott Jun 29 '11 at 13:16
    
I suspect that the reason ASP.NET MVC doesn't include UML diagrams is because Visual Studio can create them from the source code. –  user16764 Jun 29 '11 at 13:54
2  
You're operating under the false assumption that "enterprisy" is a good thing. What you learned in college about design is all lies: UML has absolutely no value. When creating a project, all you need is a general idea of what it should do and a willingness to throw it away if you do it wrong the first time. For an existing project, just skimming the main header is usually enough to get a good idea about the project layout. –  o11c Aug 26 at 6:12

4 Answers 4

up vote 9 down vote accepted

why an open source project can become successful if new-comer developer have no architectural/design document to read?

The assumption is invariably made that you know what you're doing and have a reasonably intimate understanding of what you're going (and expecting) to see.

If you look into the PHP code of the Symfony framework, for instance, you're expected to already know about dependency injection, events, the model/view/controller pattern, and so forth.

Likewise, if you dive into the C code of the linux kernel, the assumption is that you'll be realistically competent in modularity, signals, processes, threads and what not. You're also expected to have a knack to eat hexadecimal all day and excavate through core dumps with a giant shovel.

The maintainers won't go through the trouble of documenting the architecture because it's matter-of-factly stuff. On occasion, you'll find an outline of what lies where in the source tree. More typically though, the way the source tree is organized makes things self-explanatory.

In short, if you lack any of the skills that the maintainers will expect you know by the time you peek into their code, you're probably digging through stuff that is widely above your pay grade. Familiarize yourself with the concepts first - What is the MVC model? What is dependency injection? Etc. Then dive.

share|improve this answer
    
Though if you look at mailing lists the Linux kernel has extensive discussion about the architecture whenever somebody has a problem or wishes to change something. There are also quite a few documents written about it -- though not in the kernel source tree itself. –  edA-qa mort-ora-y Jun 29 '11 at 13:33

Most successful open source projects became successful because first and foremost, the program was impressive or did something no other program could do at the time. That doesn't necessarily mean the source is well-documented, since the programmers which began the project to begin with know the code well enough to not need it. It's an unfortunate reality that open source projects don't have to be well-documented. It either has to be a good program or be a mediocre program but well-documented for programmers to express interest in it.

share|improve this answer
    
In my company,it is a requirement procedure that developers must provide a Detailed Design Document before being approved write any code on a project. Is this procedure abnormal for open source project? –  TomCaps Jun 29 '11 at 10:12
    
It strikes me as a little odd that there is truly no documentation since usually there's always some sort of javadoc, though again, if you see a project like that, it's simply highly likely that the programmers who built the open source project are the same ones who currently program the open source project with no added help. –  Neil Jun 29 '11 at 10:23
5  
@TomCaps I think the biggest reason that so few FOSS projects have extensive documentation is quite simple: if your writing a little program to solve a need that you have, it's likely that since your the developer that you don't also need documentation, you are going to want to spend your time improving the program rather than writing documentation that isn't guaranteed to even be useful to anyone (what if the project is never used by anyone except the developer?). It's not best practice, but many FOSS projects are short on developer-time. –  Jeff Welling Jun 29 '11 at 11:48
4  
@TomCaps: This procedure is abnormal for most companies that I know... –  Treb Jun 29 '11 at 12:36
    
Most open source projects are not companies. You are thinking what happens when there is a project I am being paid to build, with a deadline and a budget. If you have a bunch of people coding to fill a need they have or for fun and there is no budget or client you don't have those kinds of things. –  Elin Aug 26 at 0:49

Because open source developers are usually talented and also choose project in their expertise area, they already have "documentation" within their skulls. With little exaggeration thorough documentation is needed only if you lack any of those :o)

To be honest, I don't really read "documentation" when facing unknown codebase. A quick introduction, maybe a few conceptual sketches and straight into the code! Experiment, try small changes. Works perfectly for well designed code. If I face horrible mess, then best way to learn them is to refactor bit by bit to improve clarity (ideally with help of unit-testing).

Additional reason could be plain organic design roots of these projects. Architecture is then rather evolved vision in the minds of developers than stated "documented" entity.

share|improve this answer

The reason such docs often dont exist is pretty simple: Programmers like to program, not write documentation. Especially with open source projects, which developers often contribute during their free/leisure time.

Basically, writing documentation is no fun. And if they arent getting paid for it, who wants to spend their free time doing something thats no fun?

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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