Mind Probe

How much documentation should exist in today’s software source code? At one extreme, there is the architect who believed that one line of comment is too much and that code should be self documenting. This person also used Fortran style variables names (short and with all the vowels missing). I am at the other extreme. I comment my code so with the belief that if I comment it correctly, someone else can maintain it.

What do I believe is the minimum amount of documentation that should exist in the source code? At a minimum, every public method header should be well documented. This documentation should include a list describing each parameter and what is returned. In addition, the documentation should explain what the method is suppose to do, including side-effects. My school of thought is that the public methods in a C++ class (or the equivalent in other object-oriented language) should be treated like a contract. Given a set of input, the following will happen. This does not mean that the internals of the method need to be described; it means that description should inform the caller what to expect when invoking the method. The caller should not have to reverse engineer the code that implements the method.

My wife, daughter and I enjoyed a short vacation in New Hampshire. We stayed at the Lazy Dog Inn in Chocorua, NH, just a couple of towns south of North Conway. Both of our dogs, Ada and Jack, stayed with us. The Lazy Dog Inn is run by dog lovers for dog lovers. During our vacation, we went to Story Land, drove up Mount Washington and spent lots of money in North Conway.

Yesterday at Readercon 16, the book Hal’s Worlds was publically available for the first time. There was a panel held of some of the contributors to the book. Although I was not on the panel, I am one of the contributes. Harry Stubbs (a.k.a. the author Hal Clement) lead the writers group Hal’s Pals that I belong to.

Shane Tourtellotte, the editor of the book, passed around a copy of the books to be autographed by all the authors. This book will be given to Mary Stubbs, Harry’s widow.

Today, a stranger came up to me at Readercon and asked for my autograph! This was the first autograph that I gave to someone I did not know. It was a thrilling moment for me. Although this was not the first autograph that I gave, that one went to Mary, I consider it my first fan request.

Hey, its a start.