The source may well be the most up to date and the ‘truth’, but it is by no means correct.
Although not a big fan of documenting the obvious I think that specifications should be mandatory, this way you know what the expectations were of the application, and the source code can not, and should not be the definitive source of such information. However I do agree that, particularly when bug fixing, you should be drilling down straight into the source and not much else if you want a speedy resolution, and all developers should be capable of doing this.
I think documentation pays off when you are providing reusable frameworks and other software, and even then it should be basic guidelines etc.
I agree with K Lawrence. The source code says what the application/library/widget does, not what is supposed to do. Some kind of documentation is needed.
Whenever I use a method or library created by someone else, inside my company or outside I don’t want to look into the source code unless unavoidable. I just want to know how to call it, or what it does, or what is the flow.
For self-improving reasons I will want to read the code. But for the completion of the work, shouldn’t be necessary.
While there are some correct observations regarding the availability of source code, i’d like to focus at the start of the article, where i strongly disagree.
In short, it says “Documentation always suck in many ways and it will always do. Don’t even lose your time with it, just read the code”. And since it is useless this also implies that you should not bother to write it. That’s absolutely WRONG in my opinion.
A complete documentation is important, it’s not just a reference to what a function does. It also tells you what classes are available and when you should use them. If it is properly written it’s much better than trying to read the source cose which may use a syntax you’re not used to and various implementation details that you can’t know. Try to read subversion source code.
Just yesterday i was reading a discussion on git where the developer used Javascript implicit statement separator (which means you don’t put the semicolon) and expression short-circuit instead of a normal if statement. The first of these even breaks some javascript minimizers. Am i supposed to read the code, understand these patterns, figure out what they’re doing and what that var is used to instead of just reading a good documentation? That’s crazy.
Sigh. So, another blow for cowboy/hero coding is struck. “Documentation is haaard!” So… just give up?
No. Documentation is essential. Sorry. If your code is clear, concise, self-documenting, that’s great, I totally support that (and, even if it’s not, I still want your source code), but I want to point out that that sort of lovely self-documenting code comes about because the coder thought of the person to come after, so that coder actually wrote DOCUMENTATION (it just happens to be executable).
Coding in a furball, piling up hacks, refusing to document and then handing the whole steaming mess to somebody who asks questions is chickenshit.
I have so had it with people using agile and “use the source, Luke” as an excuse for bad behavior. Yes, I know that if developers had the kind of social skills required for writing good documentation (as in: understanding the audience enough to know what questions they’ll have, given that they’re not an exact clone of you, the developer) they’d be something besides coders, but the answer is not “give up and tell 'em to read the code.”
This is one of the reasons I don’t like abstraction layers. You can’t predict exactly what they’re going to do, and you [mostly] can’t read the source code to find out.
I think I appreciate the point you’re trying to make and I agree that people would do well to learn to read the source.
However, I disagree with your statement “No matter what the documentation says, the source code is the ultimate truth, the best and most definitive and up-to-date documentation you’re likely to find.”
(Good) documentation is a description of what the software designer/programmer wanted to write, the code is what they ended up writing. If all goes well, these two are the same. But if mistakes were made, odds are only one of the two is wrong and the other offers a clue what was really intended.
Note that this also implies that, sometimes, the code can help fix broken documentation.
When I read this a couple of hours ago I agreed with it 100%, then I read about the publication of the original Prince Of Persia source code on GitHub and, although the snifter of Brandy was a tumbler of Bechrovka, sat down for a fine evening of reading through someone else’s code!
Reading the source code is not the solution to bad documentation, contributing to fixing the documentation is the proper thing to do.
Relying on source code and bypassing official documentation is asking for trouble. The source code may reveal undocumented features that are not guaranteed to be available in future versions of frameworks.
And most of the time, what inexperienced developers consider beautiful is superficial, and what they consider ugly, is battle-hardened production-ready code from master hackers.
Ole Eichhorn: “This is one of the reasons I don’t like abstraction layers. You can’t predict exactly what they’re going to do, and you [mostly] can’t read the source code to find out.”
I have the EXACT SAME issue with projects that use inversion-of-control. Makes it IMPOSSIBLE to figure out the flow of the code unless you’re using a debugger!
I also hate the current “minification” trend in web dev, because it creates source that’s completely indecipherable. Yes, I can go grab the un-minified version from the original site, but what if a specific website has made their own changes?
Code should not need documentation external to the code itself to be understandable. Fin.
I only partially agree with your statement. Reading the source is important, but reading the source is time-consuming.
When you have time contstraints, having code (especially third party libraries) where documentation and code are coherent in behaviour, and especially where all available functions (i.e. public API) are well documented, that’s a real plus and speaks for the quality of the “supplier”.
When you have API and code that don’t match, a load of undocumented features and you go on by (even obvious) trial and error, that’s not good because you always have in the back of your mind the idea that the block/component/library you’re using is not production ready and can become a thorn in your side.
Then, of course, reading a WELL WRITTEN and WELL DOCUMENTED source is a way to improve oneself, as much as reading a book in a foreign language you want to master.
I agree with the final statement from Zmaster: “Good documentation is a must, don’t oversee it.”
@Dehaul
With tools like reflector, you can look into the .NET framework fairly easily.
@Jeff
Your related posts link doesn’t work with middle click. IT simply opens the page in the same tab instead of a new one. Do me a favor, read the source and fix it. It’s annoying. I’d do it myself, but you’d be angry
Shameless plug but with the honest intent to help out those who find code reading difficult.
We are starting a free code reading study group. Initially it will be ruby, but we have plans for js.
We’re just getting started and currently discussing our first project to explore. So far 150 people have signed up so it should make for some good discussion and study.
