Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation

What is your practice for code documentation?

by ady (Deacon)
on Jun 25, 2008 at 16:56 UTC ( #693985=perlmeditation: print w/replies, xml ) Need Help??

Reading the thoughts by on Arnon Rotem-Gal-Oz on Code Readability: Documentation vs. Refactoring , I think he hits the argument on the head and drives it right home.

Currently I do most of my code development in .NET C#, using an autmated build cycle I've set up including unit-tests and coverage (which is an enormous benefit) and automatic generation of code documentation (HTML, extracted as ///code comments by Sandcastle), -- but I must admit that though our project is now 6 months down the road, I don't think that any of the developers in the project have looked at the extracted documentation more than once.

I thus agree with Arnon (on autogenerated UML and code-doc), that:

What I think is that while both of these efforts can help satisfy a customer-specific requirement for "comprehansive documentation" they have very little value in making anyone understand anything about your code. UML diagrams can only help if they are created at a higher level of abstraction than the code (which means they'd be hand-crafted) and if GhostDoc can understand your code enough to create anything useful, it means that your method and parameter names are self-descriptive anyway.

Now, I don't have extensive experience with autogenerated code documentation in Perl, apart from 'high level' POD-pages for reusable modules as exemplified by the docs on CPAN). But the discussion of putting your code documentation effort into comments (for extraction) vs. refactoring still seems relevant. I would be interested in your experiences and thoughts on this.

Best regards,
Allan Dystrup

Update: Ouch, I should probably have posted this to the Meditations section, -- feel free to move it!
  • Comment on What is your practice for code documentation?

Replies are listed 'Best First'.
Re: What is your practice for code documentation?
by samtregar (Abbot) on Jun 25, 2008 at 18:52 UTC
    My experience with auto-generated docs has been generally poor. Auto-generated docs lack "narrative flow" and often don't have any useful summary information. In my experience the most useful part of most module's docs on CPAN is the SYNOPSIS section, which gives a brief example of the usage of each method or function. For example:

    In a single page you've got pretty much everything you need to effectively use the DBI interface, laid out intelligently showing the basic groupings of methods. You'd need a pretty impressive AI to auto-generate that!


      Indeed, the synopsis is extremely valuable. Unfortunately many people leave out a very important part: the result of the code displayed. In my modules I use the same format as I use on PM code examples:
      For instance, the synopsis in List::Extract would be near useless if it wasn't for the output.

      It's easy to generate (and manually test) this by simply typing perl -Mstrict -w and then pasting the code. On your screen you now have the code, __END__, and the output following that, ready to be copied back.

      But the module may change, and an important feature of this format is that it's easy to test it. I've written, but not released, Test::Synopsis which extracts the code from the POD, compiles it, and if there were no errors or warnings, the output is compared to what's after __END__ (if anything).

      It has proven to be useful to me. I'm considering it for release.


Re: What is your practice for code documentation?
by moritz (Cardinal) on Jun 25, 2008 at 17:36 UTC
    I don't think that any of the developers in the project have looked at the extracted documentation more than once.

    I think it's totally irrelevant if they looked at the extracted documentation or not - the question is if they looked at it all. If they read it inline in the source code you just wasted one run of your extraction script.

    If they didn't look at it at all, you'd better spend your time with writing tests instead of documentation. Tests also document things in a way, and are more valuable if your colleagues don't look at the docs.

    BTW I was a bit confused, because you seem to be talking about code that is neither visible to a customer (through an API or a command line interface), nor regarded as "re-usable", because after your own logic, code has to be documented if it meets either of these two criteria. If you have large amounts of code meeting none of these criteria, chances are that documentation isn't your biggest problem at all.

      If they didn't look at it at all, you'd better spend your time with writing tests instead of documentation

      That seems a rephrasing of the main point of my post : spend your time improving the code quality (clearity, immediate understandability - by refactoring, writing tests &c) instead of investing in more extensive templated commenting for automatic doc report generation (as is popular in many coding environments these days).

      Our specific code must be understandable - not to end customers (they never see it, but they do experience its (possibly lack of) quality) - but potentially for reuse and primarily for maintenance and further development.

      Other projects may have other requirements, and thus other goals. As Arnon states in a footnote :

      * I don't underestimate the value of generating full documentation when there's such a requirement from a customer. I would prefer to convince a customer that having such a Write-Only document is a complete waste of time and trees but sometimes you can't help it. Generating documents in these situations can be a life-saver.

Re: What is your practice for code documentation?
by jethro (Monsignor) on Jun 25, 2008 at 18:46 UTC
    automatic generation of documentation is only useful if that documentation
    a) provides a view for a programmer of that code that he can't as easily get from looking at the source code or
    b) provides a document that makes interfacing/using with the code possible without needing to look at the code

    To achieve a) it isn't enough to just extract comments (handcrafted or not) or generate them, both provide no new information and should be visible in the code itself (if they are not hidden by bad coding). Arnon hits the nail on the head here. There might be some use for diagrams showing the call or object hierarchies but I don't have much experience there so don't know.

    b) is impossible in the general case (at least without true artificial intelligence). One could argue that is what is done with the POD-pages, but there you need to write the docs all by yourself, the only difference to separate documentation is that with POD the information is closer to the code.

    Btw, I don't see refactoring as a substitute for documentation. No code is that readable that a comment can't tell you faster whether or what part of that code you need to read.

      No code is that readable that a comment can't tell you faster whether or what part of that code you need to read.

      Comments lie. Even good tests rarely catch incorrect comments.

        Depends on the viewpoint. It could be argued that the code is the one lying. ;-)

        That is especially true for interface definitions. Discrepancies here are usually viewed as bugs, not as faulty documentation. Why should this be different for internal documentation? It is the interface to other programmers and should be correct

        In situations where the software has to be finished yesterday, documentation is secondary. But when you've got the time to document, you have a choice. If you care for your documentation, then the documentation shows your intent. And the code that doesn't do what is intended is buggy. Naturally out of date comments can't be avoided entirely, but it is the importance that you give their correctness that makes them valuable or noise

        The problem with this is in in projects with more than one programmer. One who doesn't take the comments serious is enough to destroy the effort of the rest.

        Stopping with my sermon now. Just let me add that I update the comments in my projects meticuosly as I have a bad memory and depend on their correctness. But I don't comment much in the code, I put the comments at the beginning of subs and methods to detail their tasks and their parameters.

Re: What is your practice for code documentation?
by eyepopslikeamosquito (Bishop) on Jun 25, 2008 at 21:19 UTC

    Chapter seven ("Documentation") of Perl Best Practices is well worth a read, no matter what language you are using, providing sound advice on separating user from technical documentation, how to subdivide your technical documentation, discursive documentation, algorithmic documentation, commenting, and more.

Re: What is your practice for code documentation?
by dragonchild (Archbishop) on Jun 25, 2008 at 18:54 UTC
    I'm running into this right now with a large optimization of DBM::Deep. As in every non-trivial piece of code, there's a lot of codesmells all over the place. I've tried doing some documentation, but it's all gone out of date very quickly.

    To me, I think the biggest key is to remove as many codesmells as possible. In doing so, the code becomes more self-evident. And, with a little reflection, that makes perfect sense. A codesmell is a place where someone goes "Why would you do that??" If you remove a codesmell, you remove a question in the reader's mind.

    That said, there are places you will always need to explain something. About 6 months ago, I started signing and dating all my comments, especially in projects where I'm the only developer. Obviously, I know I made the comment. But, as it turns out, the date on the comment has proven more useful. This is because knowing the order of the comments helps to remind me what my thinking was at that time. Since I started doing that on a $work project, I have come back to DBM::Deep where I don't have dated comments and the contrast was very stark. I feel lost without that historical context.

    If I need more than 120 characters to explain something, it's either a horrible problem with something I'm using or I screwed up somewhere. Usually, it's the latter and I need to rewrite. So, the comment gets an XXX (or TODO) on it.

    As for POD, there is very little in the way of auto-generated POD. All that stuff is written by someone, often the developer. I would love to see more non-developer-written POD as that documentation tends to be of higher quality. (This is especially true for my modules!)

    My criteria for good software:
    1. Does it work?
    2. Can someone else come in, make a change, and be reasonably certain no bugs were introduced?
Re: What is your practice for code documentation?
by Erez (Priest) on Jun 26, 2008 at 07:50 UTC

    I prefer good, well structured, clean, and cohesive code to the best comment any time. Perl, which is, to me, a language that is structured as a spoken language (assuming we would speak in routines, loops and variables), shouldn't (theoretically) be commented more than the obligatory synopsis, the API, and the overall i.e. the "man". If you have to explain anything beyond the overall things, you may need to rethink your code, not your comments.

    If your code needs a comment to be understood, it would be better to rewrite it so it's easier to understand. (Notes on Programming in C - Rob Pike)

    (Oh, and "hits the argument on the head and drives it right home"?)

    Stop saying 'script'. Stop saying 'line-noise'.
    We have nothing to lose but our metaphors.

Re: What is your practice for code documentation?
by sundialsvc4 (Abbot) on Jun 28, 2008 at 02:05 UTC

    Think about it this way:   how well does a telephone directory describe a town?

    When I am looking at the documentation for a piece of computer software, sometimes I am looking for a directory. I really do just want to know where a particular place or thing is. But... not most of the time. In fact, almost never. No.

    What I really want is:   to read the original developer's thoughts. I want to get a glimpse of her intent when she designed and then wrote that particular piece of code. Truly, the final software is very-much an expression of that, and this is something that no amount of computer-generated recyclables will tell me.

Log In?

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlmeditation [id://693985]
Approved by GrandFather
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others making s'mores by the fire in the courtyard of the Monastery: (2)
As of 2022-08-10 02:49 GMT
Find Nodes?
    Voting Booth?

    No recent polls found