[brailleblaster] Re: Latest Draft of BrailleBlaster attached
- From: "John J. Boyer" <john.boyer@xxxxxxxxxxxxxxxxx>
- To: brailleblaster@xxxxxxxxxxxxx
- Date: Tue, 28 Dec 2010 18:44:12 -0600
Susan,
Thanks for the link. The javapractices site should be a great source for
best practices.
I'm not surprised that literate programming never caught on. The
documentation by means of comments in Java and Python is much more
practical.
John
On Tue, Dec 28, 2010 at 05:29:58PM -0700, Susan Jolly wrote:
> John,
>
> I was trying to make less work for you, not more. If you get in the habit
> of putting a short package.html file or package-info.java file in the
> directory every time you create a package directory, then it just takes an
> extra minute or so and your major API documentation is done. Same thing
> with putting a one-sentence description of a class just above the class
> declaration every time you create a new class.
>
> I was unaware of package-info.java before you mentioned it. Apparently
> since Java 1.5 this is the preferred alternative since it allows for
> package-level annotations and is less cluttered. However, you can still use
> a package.html file if you prefer.
>
> This is a very nice write-up about why and how to use javadoc.
> http://www.javapractices.com/topic/TopicAction.do?Id=60
> I'd not run across the javapractices site before but it looks really useful.
>
> By the way, javadoc is simply a tool for extracting comments from Java
> source code and publishing them in a certain format. This is very
> different from literate programming. With a literate programming system
> you write your literate source in a higher-level language that intermixes
> code snippets and documentation in what Donald Knuth called a Web. You must
> then use a preprocessor to turn the literate source into actual source code
> every time you want to compile. I don't believe literate programming has
> ever really caught on.
>
> Susan
>
--
John J. Boyer; President, Chief Software Developer
Abilitiessoft, Inc.
http://www.abilitiessoft.com
Madison, Wisconsin USA
Developing software for people with disabilities
Other related posts:
