Comments on: Software Engineers should keep lab notebooks http://blog.nelhage.com/2010/05/software-and-lab-notebooks/ It's software. It's made of bugs. Fri, 03 Feb 2012 17:48:35 +0000 hourly 1 http://wordpress.org/?v=3.2.1 By: Marc http://blog.nelhage.com/2010/05/software-and-lab-notebooks/comment-page-1/#comment-1039 Marc Tue, 04 May 2010 05:15:03 +0000 http://blog.nelhage.com/?p=217#comment-1039 <p>Nice. Two practical lessonsin this department:</p> <ol> <li><p>If you call the lab notebook a wiki, it may help at least some people swallow the pill more easily. The right wiki will also provide history and encourage editing which is a plus. This has proven especially valuable for tasks which are not just conventional coding tasks. Adding to your list: setting up a dev environment (I wish on most platforms this was dominated by aptitude install ... but it can get much more complicated), release engineering, operational procedures, etc. Of course, automation can help, but sometimes the cost/benefit favors documenting a manual process. </p></li> <li><p>At my robotics startup, we have adopted the code inspection process from "Code Complete". It is not without flaws, but in general I believe it has improved quality. Apropos to this post one part of the review process is for a scribe who is not the author to write down all observed defects. This keeps a reasonable record of changes after the initial dev effort (but of course you'll need some other mechanism to help with that).</p></li> </ol> Nice. Two practical lessonsin this department:

  1. If you call the lab notebook a wiki, it may help at least some people swallow the pill more easily. The right wiki will also provide history and encourage editing which is a plus. This has proven especially valuable for tasks which are not just conventional coding tasks. Adding to your list: setting up a dev environment (I wish on most platforms this was dominated by aptitude install … but it can get much more complicated), release engineering, operational procedures, etc. Of course, automation can help, but sometimes the cost/benefit favors documenting a manual process.

  2. At my robotics startup, we have adopted the code inspection process from “Code Complete”. It is not without flaws, but in general I believe it has improved quality. Apropos to this post one part of the review process is for a scribe who is not the author to write down all observed defects. This keeps a reasonable record of changes after the initial dev effort (but of course you’ll need some other mechanism to help with that).

]]> By: Kevin Riggle http://blog.nelhage.com/2010/05/software-and-lab-notebooks/comment-page-1/#comment-1037 Kevin Riggle Tue, 04 May 2010 00:15:24 +0000 http://blog.nelhage.com/?p=217#comment-1037 <p>I think this is a place where open-source projects conducted largely online have a big advantage -- when all discussion takes place over e-mail and IM, and they're publicly logged, the project gets a pretty clear record of the decisions the group made without the group having to take much extra effort to do so. Obviously it's not 100%, but I think it's better there than in most of the proprietary software I've worked on, where things are more often conveyed verbally and thus more likely to get lost or misremembered.</p> I think this is a place where open-source projects conducted largely online have a big advantage — when all discussion takes place over e-mail and IM, and they’re publicly logged, the project gets a pretty clear record of the decisions the group made without the group having to take much extra effort to do so. Obviously it’s not 100%, but I think it’s better there than in most of the proprietary software I’ve worked on, where things are more often conveyed verbally and thus more likely to get lost or misremembered.

]]> By: Jeffrey Bosboom http://blog.nelhage.com/2010/05/software-and-lab-notebooks/comment-page-1/#comment-1036 Jeffrey Bosboom Mon, 03 May 2010 20:25:07 +0000 http://blog.nelhage.com/?p=217#comment-1036 <p>From the <a href="http://www.boost.org/development/requirements.html#Rationale_rationale" rel="nofollow">Boost library requirements and guidelines "rationale rationale"</a>:</p> <p>"Beman Dawes comments: Failure to supply contemporaneous rationale for design decisions is a major defect in many software projects. Lack of accurate rationale causes issues to be revisited endlessly, causes maintenance bugs when a maintainer changes something without realizing it was done a certain way for some purpose, and shortens the useful lifetime of software.</p> <p>Rationale is fairly easy to provide at the time decisions are made, but very hard to accurately recover even a short time later."</p> <p>(As a side note, when reading this post in Thunderbird, clicking anywhere in the comments area caused Firefox to open a tab at the submit comments php page, with no content. Not sure if that's Thunderbird's fault, or WordPress's.)</p> From the Boost library requirements and guidelines “rationale rationale”:

“Beman Dawes comments: Failure to supply contemporaneous rationale for design decisions is a major defect in many software projects. Lack of accurate rationale causes issues to be revisited endlessly, causes maintenance bugs when a maintainer changes something without realizing it was done a certain way for some purpose, and shortens the useful lifetime of software.

Rationale is fairly easy to provide at the time decisions are made, but very hard to accurately recover even a short time later.”

(As a side note, when reading this post in Thunderbird, clicking anywhere in the comments area caused Firefox to open a tab at the submit comments php page, with no content. Not sure if that’s Thunderbird’s fault, or WordPress’s.)

]]>