This is an article I originally wrote for the brazilian online magazine
DevMedia’s Mobile Magazine.
This first part is the article’s introduction, so seat back and relax. Soon I’ll
post the second - and final - part with a tutorial to the Apple like
documentation generator appledoc.
“In the agile programming environment, using methodologies such as SCRUM, Agile
and Lean, we can’t always document our sources. After all, pragmatics as we
developers are, why would we lose time if the documentation won’t be compiled,
won’t do any difference in the code’s performance and demands a considerable
slice of our time? But despite all that, the lack of documentation hurts. A lot.
Who’s familiarised, knows that in the ultra accelerated rhythm of startups,
where everything is at the top of the list, there’s not always time to apply
some of the good programming technics that aren’t crucial to the sanity and
speed of the code. Oftenly, there’s no time to formally test classes and methods
because of the virtually null due time that is given. It’s easy to find
developers awake all night in hackatons to successfully deliver that key
feature that will make “the whole difference”. Test? Document? Review? There’s
so much to do and so little time!
That’s the reality of many young developers who enter this ultra competitive
environment searching for the dream of running their own companies. The
responsibilty of satisfying potential investors, the pressure for deploys and
the client’s needs frequently obfuscate technics that improve development and
maintenance experiences, but that are not considered primordial to the
construction of an application. How often didn’t I went back to an undocumented
code done less than two months before and thought “what the flock does this
loop do?” or “why, on earth, is this class here and not there?” Of course,
when those lines of code were written, everything made perfect sense, but the
moment those ifs and fors went out of the conscious mind, their meaning were
long gone. After all, quoting the chinese saying: “the ink is better than memory”.
So let us document. It doesn’t hurt, doesn’t make you fat and isn’t illegal.
Actually, documenting is like eating vegetables: no one really likes it, but we
do it hopping that, in the end, it’s worth the result. But unlike the vegetables,
it’s proved that documenting helps. Contrary to the common thought, the time
spent documenting a day’s work is reasonably irrelevant and the benefit in return
is definitely worthy. With practice and experience, no more than 30 minutes can
be lost documenting everything that was made in a whole day. That way, the
developer stays focused in his activity and doesn’t deviates doing other stuff
that draws his attention or stand in his way of writing the best possible
algorithm. Therefore, don’t wait until the end of the week, when the work pile
up, part of the features were already forgotten and we’re all dying to that
ice-cold friday-night-beer. Personally, I recommend documenting in the end of
the day. In my case, it’s always the last thing I do before leaving, because
everything is still fresh in memory and the amount of code produced in one day
doesn’t compare to what’s done in one week. If that’s not enough, I realised
that I do a final unconscious revision before the final commit when I’m
passing by the code documenting it.
A well documented code is good for everybody. What would be of us without the
independent frameworks, packages and repositories used daily if they weren’t
documented, or even had a bad documentation? Even senior programmers, frequently,
return to Apple’s documentation to a better understanding of Cocoa’s classes.
Whether consulting a less used protocol, or lower level functions to manage
sockets, threads or semaphores. Nobody can remember everything, so don’t
try it, you’re not an elephant. It’s not rare to find developers who use the
documentation as a last resource to understanding some tool. This line of thought
makes sense if we think that we want everything to be as explained as possible
so we don’t lose any time trying to interpretate any possible use, when trying
to comprehend some feature. But we must never forget that even when visiting
forums, asking more experienced developers or reading articles in blogs,
EVERYTHING had a documentation as basis. Well, even this article wouldn’t exist
if wasn’t for appledoc’s documentation.
Documenting - or at least commenting - source codes is fundamental to the
intelligibility of the code. Implementing these technics with developers that
never done it, oftenly is seen with prejudice and suspicion that are common to
the staunch and stubborn nature of young programmers. I must confess that I
didn’t wanted to document when people first told me to. Moreover, because of
it’s so unusual syntax, it’s interesting to verbalize what’s developed in ObjC
to ease it’s lecture, specially by more unexperienced programmers.
As time goes by, with the expansion of the startup, the pressure and need of
code documentation is felt. Contrary to many programming languages - such as
Java with it’s hideous GUI Javadoc - Objective-C doesn’t have an “official”
documentation generator. In our quest to find a differentiated framework, which
could make us feel as if we were really making difference, we found the excellent
appledoc that, using code comments à la
Javadoc, generates Apple like documentation, with a docset automagically
installed in XCode, static HTML sources which can be uploaded to a cloud (vide
NSStringMask which uses
appledoc) and an interface identical to Cocoa’s.
Among appledoc)’s already described advantages,
are also the documentation parsing through code comments, wich allow the developer
to consult the documentation without the need of opening a new window, since
everything is in the code. The integration with XCode allows the visualisation of
tooltips with quick access to the documentation by simply holding the Option
key and clicking a method or class. Moreover, by “compiling” appledoc)
in your documented project, the library’s docset is already imported to your
Organizer. Simple or not? But, undoubtedly, appledoc)’s
main advantage is it’s interface that’s identical to Apple’s documentation. I
think it’s very unlikely that there’s any ObjC developer that has never read
Cocoa’s documentation, be the one embedded on XCode or the on in Apples developers
portal. By reusing the known model, it terminates the problem of having to
familiarise to a new layout.”
Soon I’ll be posting the second part with a tutorial.
