Home > SD in general > On documentation (or lack thereof)

On documentation (or lack thereof)

There are probably enough books, articles, blogs and tweets on documentation to fill a library, so there’s absolutely no need that I vent my thoughts. Fsck it, I’m going to do so anyway, spurred on by a recent tweet “discussion” and a general lack of Javadoc on classes of one of my favorite frameworks. And don’t worry: I’ll make it personal and not based on any existing literature or body of knowledge whatsoever, so it’s completely fresh and unadulterated 😉

My initial grumbling tweet read “Hmmm, why do devs confuse beta/experimental with ‘no need to document’.” To which I got the reply from @markijbema: “Most documentation is still too far away from coding. I’m willing to document if it’s DRY and away from my normal workflow.” (Note that this post is not a rant about that tweet: the tweet just happened to trigger me to write up the beliefs I’ve had for some time now.)

Now, I completely agree with the DRY-part. After all, we’ve all seen code like this:

 * Increments the given integer with 1.
 * @return The given integer, incremented with 1.
 * @param i
 *            - the integer to be incremented.

public int increment(int i) {
  return ++i; // increment i with 1 and return

Good for your LoC count, bad for everything else. This complies with Mark’s remark about ‘documentation being (still) too far away from coding’. However, good documentation is not too close to the code, as documentation should augment the code but let the code itself speak for itself as much as possible. To give one good reference, despite all my promises in the first paragraph: go read Kent Beck’s Implementation Patterns.

I completely disagree with Mark’s assertion that documenting shouldn’t be part of a normal workflow, though. There are a couple of reasons for this. First of all, if it isn’t part of a normal workflow, it’s not going to happen, period. Now, a lack of documentation could very well be more desirable than bad documentation, since it can’t put anyone on the wrong foot and doesn’t cost any effort to produce.

Alas, the real world often insists on some documentation which usually means it will be done poorly. By someone else than an original coder. That someone else being a non-coder or a very bad one since he/she isn’t allowed to touch the code anymore. And it’s done about 5 minutes before the last deadline in about as many minutes. (This goes some way in explaining why 70% of all software never makes it to Production.)

Secondly, the effort it takes to write good documentation is an inverse measure of the understandability or the engineering quality of the code: if it’s difficult to describe what some piece of code does, then I’ll bet that the code is difficult to understand, hence difficult to use, to maintain and to change. If it’s easy to write good documentation, then you’re done in no time at all and there’s no reason why you shouldn’t have taken the effort 🙂

How I do it (or at least: try to)

For myself, I tend to document my code on the ‘module’ level (which can mean anything from a singleJava package to a coherent set of Eclipse projects – whatever constitutes a sensible, functional/technical breakup of the code base), on the class level and one the feature level (meaning fields or methods). Also, I tend to document design decisions in the code, right at the point where I made them.

On the module level, I stick to high-level stuff (what am I trying to achieve, what are the dependencies in terms of infrastructure, libraries and development environment, what does the road map look like and how can someone influence it, how can one contribute), possibly combined with pointers to ‘hooks’ in the code base which act as starting points from which you can traverse the code base in an meaningful direction.

On the class level I tend to document aspects like the class’ responsibility and usage patterns –What is this class intended to achieve? How can this class be used by other classes to that end?- and nothing more (apart from design decisions and such). Note that the usage patterns tend to include dependencies.

I’ve often noticed that documenting the class’ responsibility in a high-level manner is often already useful for yourself, but it’s especially important for other people who try to understand your code base. As an example: I know quite a bit about Xtext, but its code base generally lacks JavaDoc which means I have to second-guess about the function of a class and how to use. This also means I’m only going to notice gems like o.e.x.util.OnChangeEvictingCache until I stumble across them and see someone else use it.

On the feature level, I try to be as succinct as possible, especially with private features, but I don’t restrict documentation to public features. After all, visibility should be about separation of concerns, coherence and loose coupling and doesn’t pertain to the code’s understandability as it transcends the boundaries of visibility. I think quite a bit about good method names, but also about parameter names, even in languages that only have positional instead of named parameters (like Java) since these do show up in the documentation and can be used to convey meaning. Or the other way around: badly chosen names can cause more confusion than documentation can cure.

Overall, I try to tie the documentation as much as possible to the actual code by use of JavaDoc or similar DSLs, since that gives me a kind of limited static type safety on the documentation. At any point I reserve the “how” for in-code comments (e.g., Java single or multi-line comments) and the “what” and “why” for the ‘official documentation’ (e.g., JavaDoc).

Categories: SD in general
  1. November 16, 2011 at 5:50 pm

    It’s always fun to go through and run the JavaDoc checkstyle rules against a code base. Typically you’ll get several thousand errors reported because of poor, incorrect, or non-existent javadoc.

    Eclipse also can flag these ahead of time in the IDE. The settings are stored under, Preferences->Java->Compiler->JavaDoc, and they are all currently set to Ignore by default. Changing these from Ignore to either Warn or Error, will help flag them within the IDE.

    There is nothing more frustrating from a person trying to use a framework or an api, as bad or missing javadoc.

    • November 16, 2011 at 6:18 pm

      True, but I think those auto-checkers aren’t that useful since they enforce presence and syntactical correctness of JavaDoc, but can’t judge the semantical correctness. The end result is often “JavaDoc for the sake of JavaDoc” in which all required metadata is filled out (minimally) without adding any value but with some obvious (at least, for humans) repetition. In turn, this results in JavaDoc occluding the actual code, making it less readable, and being ignored because it doesn’t actually convey anything useful.

      If it were possible to only generate a warning/error for a missing class-level JavaDoc, then I’d switch it on right away. But I’m not going to put up with a warning which wants me to add 5 lines of comment bloat to a 2-line method.

  2. November 17, 2011 at 8:46 am

    Could not agree more with this !
    Actually, I’m working on an Eclipse Project called “Intent” (released under Mylyn Docs), which purpose is to ease the writing of high-level documentation.

    Even if the rules you precognize are great,it remains difficult for newcomers who discover the code to get easily high-level informations (requirements, design decisions…).

    Intent is about synchronizing high-level documentation with any concrete development artifact (Java classes, but also plugin dependencies, code samples on the internet, models, or anything you want as long at you have bridges).

    If you are interested, here is some useful links :
    – A transcript of the talk I gave at EclipseCon Europe : http://www.eclipse.org/intent/pages/transcripts/2011_EclipseConEurope/Intent_ece2011.htm
    – Intent wiki : http://wiki.eclipse.org/Intent
    – The installation guide : http://wiki.eclipse.org/Intent/Installation_Guide

    Cheers !

    • November 17, 2011 at 9:17 am

      Cool stuff! Installing right now…

  3. November 17, 2011 at 10:01 am

    Great ! Do not hesitate to spam me on Intent forum http://www.eclipse.org/forums/index.php?t=thread&frm_id=219 , we’re really open to feedbacks (good or bad) and suggestions, the project is just starting 🙂

  1. November 17, 2011 at 6:42 am
  2. December 1, 2011 at 10:46 am

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: