[brailleblaster] Re: Latest Draft of BrailleBlaster attached
- From: "John J. Boyer" <johnjboyer@xxxxxxxxxxxxx>
- To: brailleblaster@xxxxxxxxxxxxx
- Date: Tue, 28 Dec 2010 16:54:07 -0600
All right, you guys. I'll put more documentationn in my code and even
read up on javadoc. I've never seen a package.html file in all my
studying of Java source code. Occasionally I see a package-info.java
file.
This is like the "literate programming" that the late Eitan Gurari was
so fond of.
During this week, however, I'm going to concentrate in finding some
nasty problems in the C libraries and getting them to build on my VPS,
which is where I do Java development. It uses CentOS, and the autotools
seem to be broken.
John
On Tue, Dec 28, 2010 at 03:01:34PM -0700, Susan Jolly wrote:
> Years ago I had an officemate who said that if it took more than one simple
> sentence to state the function of a [Fortran] subroutine, it was doing too
> much. I think that is a good summary of how the feedback between writing
> internal documentation and coding an implementation can often help you to
> avoid documentation errors and, at the same time, to write better code.
> For example, the top-level documentation of a class might simply be,
> "Objects of this class handle input of a user configuration file." Note
> the absence of the word "and." If this statement is originally correct, it
> should likely stay correct.
>
> Of course, a high-level class like this one would typically hand off much
> of its actual lower-level work to other classes. In fact, the suggested
> documentation helps you realize this. After all, it doesn't say "input AND
> storage" of the user file. So that reminds you of the desirability of
> another class that is just a data structure for representing a user
> configuration. And by then, you start to appreciate modularity. If for
> example, you want to develop some piece of code that relies on a user
> configuration but you don't want or need to get one from input, you can
> just create one directly.
>
> As another example, it might not be until later that you realize there is a
> need for handling multiple user configuration files. Your previous
> documentation referencing "a configuration file" should make you thinking
> seriously about the probably preferable solution of developing a new class
> that "manages the use of multiple configuration files" rather than adding
> to the functionality of the original class such that its top-level
> documentation is no longer correct.
>
> Of course you aren't always going to come up with the best functional
> decomposition on your first try. That's where refactoring comes in. But it
> has been my experience that my own code is easier to reuse, easier to
> maintain, and easier to extend the more closely I follow my old
> officemate's advice.
>
> SusanJ
>
>
--
My websites:
GodTouches Digital Ministry, Inc. http://www.godtouches.org
Abilitiessoft, Inc. http://www.abilitiessoft.com
BrailleBlaster http://www.brailleblaster.org
Location: Madison, WI, USA
Other related posts:
