<pedrocorreia.net ⁄>

<Why documentation matters - intent and abstraction ⁄ >

clicks: 4444 4444 2006-10-19 2006-10-19 goto misc myNews misc  Bookmark This Bookmark This

OK so I know I'm swimming against the tide on this one - so let's just say it "I'm in favor of documentation for software". Eek! Yowza!
Now I don't mean docs for users (although that's important) I mean MS Word documents with nice box and UML diagrams for developers - not just javadoc.

I'd say of all the developers I've worked with, probably 80% dislike (if not disdain) documentation and probably 70% don't even see a need for it. Maybe a little javadoc but hey the signature
"public void doStuff(Object o) throws Exception"
is 100% clear right? WRONG!

For managers the percentages are a little better (60%/50% like documentation) but it is not by much and mostly its because they want to know exactly what's going on and *NEED* documentation.

I see several aspects of documentation as very important and useful to developers primarily and to the enterprise at large secondarily:

1) New Developers / Testers on your team
So you show some 250 kLOC to a new senior engineer, give them a sparse functional spec and ask them to go coding some new feature!?!?! -Personally, I think the learning curve will be huge. Which components do they need to change?
Which components do they need to ignore?
Which interfaces do they need to extend?
How do they test it?
What standards need to be followed - syntax, threading, resources etc.?

Now I'm not talking about creating a 500 page CMM tome - just, say, a 20-40 page document describing layers, the high level architecture and what components do what.

I mean it's easier to read a 20 page architecture / design doc than it is 250 kLoC!

2) Intent
OK so the code is self-documenting and debugged right? So I don't need documentation? Well no! If you've read Knuth you know that very few programs are provably correct (well not any one beyond a few hundred lines in the real world). So your code does what you want it to do? That's great, but does it do what it is *SUPPOSED* to do?
Well maybe you know (or will after more testing) but will anyone else?
More importantly what *YOU* think you need to implement and what your tech lead / architect need to implement can be very different.
Documentation can help elucidate the intent of your program.

3) Clarification
This is similar to #2 but the audience is different - it's YOU - the developer! That's why writing is useful - putting stuff down on paper removes some of the "abstract-ness" and "fuzziness" and makes things more concrete - that is it makes things seem more clearly right (or clearly wrong) or clearly incomplete. OK writing can also make clear things fuzzy too but it helps, excuse the pun, keep folks on the same page.

este é só um excerto do artigo, para aceder ao artigo completo, clique no link em baixo:
this is just a small excerpt from the article, to access the full article please click in the link below:


Subscribe News RSS  Subscribe News Updates by E-mail

myNews <myNews show="rand" cat="misc" ⁄>

Adobe Photoshop CS6: Improvements for Web and UI Designers new ...

Photoshop CS6 has been hailed as a huge improvement for web and UI designers. I'm going to share wit (...)

clicks: 20668 20668 2012-05-14 2012-05-14 goto url (new window) webdesign.tutsp... goto myNews misc

Camera Exposure Modes Explained new ...

If you're just getting started with photography, the letters on your camera's dial might feel like h (...)

clicks: 17348 17348 2012-05-13 2012-05-13 goto url (new window) photo.tutsplus.... goto myNews misc

45 Fresh Collection of High Quality Free PSD Files new ...

What else can be so great for a designer than finding out high quality Photoshop PSD files? This is (...)

clicks: 10730 10730 2012-05-09 2012-05-09 goto url (new window) smashingapps.co... goto myNews misc

15 Free High Quality ToolTip PSD's new ...

A tooltip or infotip can be defined as a graphical hint that is incorporated with the website design (...)

clicks: 12586 12586 2012-05-07 2012-05-07 goto url (new window) smashingapps.co... goto myNews misc

40+ Elegant Examples of River Photography

River photography is one of the beautiful type of photography, photographers take pleasure in this w (...)

clicks: 8400 8400 2012-05-04 2012-05-04 goto url (new window) smashingbuzz.co... goto myNews misc

40 Fresh And High Quality Free Icon Sets In PSD Format

Here is yet another exciting collection of high quality Free Icon PSD files for the designers that t (...)

clicks: 8630 8630 2012-02-19 2012-02-19 goto url (new window) smashingapps.co... goto myNews misc

15 jQuery Calendar Date Picker Plugins

In this collection, you will see some of the best jQuery Calendar Date Picker Plugins that will allo (...)

clicks: 8566 8566 2012-02-18 2012-02-18 goto url (new window) smashingapps.co... goto myNews misc

50 Beautiful Yet Free HTML5 And CSS3 Templates

HTML5 templates are getting very popular these days because all professional HTML5 templates are com (...)

clicks: 9148 9148 2012-02-17 2012-02-17 goto url (new window) smashingapps.co... goto myNews misc