I really like the way JavaDoc works. I haven't used RPGDoc, as Jon suggested, but I imagine it works on the same concept.
JavaDoc reads comments and certain lines from your source file and produces HTML. The HTML is indexed in a orderly structure with a separate page for each class linked from the index. You take the output from the JavaDoc run and drop it in a directory that is served from a webserver package like HTTP Server Powered by Apache and give eveyone the URL. It's like an automatically generated wiki. Here's a public example
http://javadoc.midrange.com/jtopen/index.html.
The comments follow a special structure that would work in free-form RPG. Any comment that starts with /** is considered JavaDoc. The comment must also preceed certain line types such as a class or method declaration. There are special character combinations that influence how JavaDoc will build the HTML, for instance, @param introduces your explanation of a parameter.
Most of the source editors for Java will build a JavaDoc skeleton with all the special strings for you when you type /** and press enter just before one of the line types.
JavaDoc is included in the standard jdk distribution and is therefore as free as the jdk is.
Then it's just a matter of training anyone who writes code for your shop to study your JavaDoc before writing any new code. That's always the hard part.
-----Original Message-----
From: midrange-l-bounces@xxxxxxxxxxxx [mailto:midrange-l-bounces@xxxxxxxxxxxx] On Behalf Of Sam_L
Sent: Thursday, January 05, 2012 8:19 PM
To: midrange-l@xxxxxxxxxxxx
Subject: In-house Reusable Code: Publishing and Documenting
Reusable code is a great concept, but unless you know a routine exists and what it does you can't use it.
We're a small shop and we have some reusable service programs and commands. The few heavily used commands are easy to remember, but folk forget about the rest. (I just bumped into one today that *I* created a year ago and had completely forgotten about.)
Have any of you found good answers to either of these questions for a shop with 5 or more developers?
1) How do y'all make people aware what reusable routines exist?
2) How do folk find what a reusable routine does, short of reading the code?
--
This is the Midrange Systems Technical Discussion (MIDRANGE-L) mailing list To post a message email: MIDRANGE-L@xxxxxxxxxxxx To subscribe, unsubscribe, or change list options,
visit:
http://lists.midrange.com/mailman/listinfo/midrange-l
or email: MIDRANGE-L-request@xxxxxxxxxxxx Before posting, please take a moment to review the archives at
http://archive.midrange.com/midrange-l.
midrange.com
