Want to read Slashdot from your mobile device? Point it at m.slashdot.org and keep reading!


Forgot your password?
Bug Programming Software

Documentation As a Bug-Finding Tool 188

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:Indeed (Score:4, Informative)

    by grcumb ( 781340 ) on Sunday April 15, 2012 @02:38AM (#39691293) Homepage Journal

    Explaining your work is a great way to demonstrate that you actually understand it.

    My standard development process is:

    1. Document the method;
    2. Write the tests for the method;
    3. Write the code for the method;
    4. Make corrections to each until everything works;
    5. Move on to the next method.

    My rationale is precisely that: I'm not really sure I know what I'm doing until I've described it, then figured out how my idea might fail.

    Forgive my ignorance, but doesn't everyone do this?

  • by Elf Sternberg ( 13087 ) on Sunday April 15, 2012 @02:59AM (#39691351) Homepage

    Oh, come on, Literate Programming has been around for 30 years! Knuth made exactly this argument in his 1984 essay entitled, surprisingly enough, "Literate Programming!" Wikipedia asserts in it "Literate Programming" entry: "According to Knuth, literate programming provides for higher-quality programs, since it forces programmers to explicitly state the thoughts behind the program, making poorly thought-out design decisions more obvious. Knuth also claims that literate programming provides a first-rate documentation system, which is not an add-on, but is grown naturally in the process of exposition of one's thoughts during a program creation. The resulting documentation allows authors to restart their own thought processes at any later time, and allows other programmers to understand the construction of the program more easily."

    Congratulations to Slashdot for posting about some kid rediscovering an ancient technology by a revered master of the craft. What's next? "Snot-nosed highschooler discovers GOTO is a bad idea?"

This process can check if this value is zero, and if it is, it does something child-like. -- Forbes Burkowski, CS 454, University of Washington