Forgot your password?
typodupeerror
Bug Programming Software

Documentation As a Bug-Finding Tool 188

Posted by Soulskill
from the //-this-is-where-i-forgot-a-parenthesis dept.
New submitter Sekrimo writes "This article discusses an interesting advantage to writing documentation. While the author acknowledges that developers often write documentation so that others may better understand their code, he claims documenting can also be a useful way to find bugs before they ever become an issue. Taking the time to write this documentation helps to ensure that you've thought through every aspect of your program fully, and cleared up any issues that may arise."
This discussion has been archived. No new comments can be posted.

Documentation As a Bug-Finding Tool

Comments Filter:
  • Re:Common knowledge? (Score:5, Interesting)

    by ZackSchil (560462) on Sunday April 15, 2012 @01:43AM (#39691319)

    Just as often, while writing documentation on code I just wrote, I've thrown up my hands, and thought "this is so ridiculous and embarrassing that I can't be associated with it", and I went back and re-wrote it to do it the right way. The act of documenting it revealed you left too much undone, or too many situations un-handled.

    This is by far more common for me as well. I'll find myself describing some really brittle setup process or some common operation that seems to take a thousand steps, get embarrassed over how bad it is, and then go fix the code. More than once, I've written sophisticated automatic parameter selection code because it was easier than finishing the documentation I had started explaining to the user how to set up parameters properly.

  • Knuth (Score:5, Interesting)

    by phantomfive (622387) on Sunday April 15, 2012 @02:31AM (#39691437) Journal
    I believe this is the method Knuth recommended, and formed the beginnings of the idea of literate programming [wikipedia.org].
  • Re:Indeed (Score:4, Interesting)

    by purpledinoz (573045) on Sunday April 15, 2012 @02:48AM (#39691473)
    I think most people to this:

    Write method.
    Write unit tests.
    Fix until it works.
    Write documentation.

    I generally find that code documentation is a lot better if the document first approach is used. In the above approach, the method is done, and the documentation becomes a chore.
  • by sn00ker (172521) on Sunday April 15, 2012 @03:30AM (#39691573) Homepage
    Titled They Write the Right Stuff [fastcompany.com] it looks at the coding practices at the company that wrote the control software for the space shuttles. If you want to know about documentation as a bug-finding tool, this is pretty much the holy grail.

    Consider these stats : the last three versions of the program -- each 420,000 lines long-had just one error each. The last 11 versions of this software had a total of 17 errors. Commercial programs of equivalent complexity would have 5,000 errors.
    ...
    Take the upgrade of the software to permit the shuttle to navigate with Global Positioning Satellites, a change that involves just 1.5% of the program, or 6,366 lines of code. The specs for that one change run 2,500 pages, a volume thicker than a phone book.

  • by ciaran.mchale (1018214) on Sunday April 15, 2012 @03:59AM (#39691631) Homepage

    There is an old joke: "The definition of promiscuous is somebody who has more sex than you do". From reading TFA and some of the comments on slashdot, I get the feeling that the definition of documentation is equally subjective and self-serving for developers. Some developers think that writing documentation means adding comments to code. Others feel it involves writing Javadoc/Doxygen-style comments at the start of every class and method, and then generating HTML from that. Yet others feel that documentation hasn't been written unless it involves an architectural description.

    When I am working on my own open-source projects, I feel that documentation isn't complete until I have written a few hundred pages of text that aim to be cover most/all of the following: (1) API reference guide, (2) programming tutorial, (3) user guide, (4) architectural guide, and (5) suggestions for "future work" that I hope other people will volunteer to do. Yes, I recognise that I am a bit extreme in the amount of effort I put into writing documentation. However, it does enable me to elaborate on the thesis of TFA: attempting to write such a comprehensive amount of documentation often highlights not just coding bugs, but also architectural flaws. This causes me to work in an iterative manner. I implement a first draft version of the code. Then I start documenting it, and when I encounter a part of the software that is difficult to explain, I realise that I need to re-architect the code base a bit. So I do that, and then get back to writing documentation, which causes me to notice another difficult-to-explain issue with the code. Working in this manner is slow, and I suspect it wouldn't work in a business with time-to-market pressures, but I find it gives excellent results in my own, non-time-pressured open-source projects. I touched on this issue [config4star.org] in the documentation for one of my open-source projects.

  • Re:Common knowledge? (Score:5, Interesting)

    by TheRaven64 (641858) on Sunday April 15, 2012 @05:49AM (#39691949) Journal
    There's a very old saying:

    If the code and documentation disagree, then they're both wrong

    The documentation itself is probably not the important bit. The thing that a lot of programmers seem to do wrong is getting the correct ordering of the thinking and coding steps mixed up. Writing documentation first means that you have to do the thinking before the coding, and that eliminates a whole load of problems.

  • Re:Common knowledge? (Score:5, Interesting)

    by SimonInOz (579741) on Sunday April 15, 2012 @08:51AM (#39692725)

    When I was involved in writing one of the first packet switching systems in Europe (AT&T, Belgium, 1979), we found a brilliant way to fix bugs was to explain the bug (and thus the operation of the program) to someone. They didn't have to do much, just nod and look interested.
    Then usually about halfway though, the hapless coder (eg me) would go "Oh shit" ... and the listener cold then leave.
    We called it the "tailors dummy" approach to debugging.

    A bit like pair programming, only less labour intensive.

Optimization hinders evolution.

Working...