For our current project, my team cobbled together a tool that reads in each Jess rules module and writes out source for a trivial java class which has one do-nothing method for every rule. We copy the Jess documentation comment for each rule into a JavaDoc style comment on its surrogate method. Once we have something that looks like normal Java documentation, we can import the rule comments into our Rational Rose design model using their standard Java reverse engineering tools. This allows us to extract documentation from Jess that superficially looks like the low-level documentation we extract from our Java code.
While everything in this low-level documentation may be accurate, it provides very little insight into how sets of rules interact at the higher levels. With our Java OO code, we normally supplement the Java Doc comments with various UML diagrams to show how objects retain associations with each other and how sequences of method calls build up to higher level functionality. None of the normal UML diagrams seems to describe the overall flow of our ruleset very well. All of our attempts to describe the large scale operation of the rules in UML feel forced, and contain so many approximations and omissions that we fear they may be doing more harm than good. I am trying to question several of my basic assumptions here, and would appreciate any insights from people who have had to document and maintain medium to large rule based systems. 1) Is there a good way to document a rulebased system in UML that I am just not seeing? 2) Is there a non-UML methodology that better describes the top-level structure of a rule-based system? 3) Is software based on pure declarative programming ideally lacking in top level structure? The existence of rule modules and salience levels seem to impose some structure on the software. These features of the Jess language may break down the purity of the declarative programming style, but they seem necessary. -----Original Message----- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of friedman_hill ernest j Sent: Friday, June 23, 2006 9:23 PM To: [email protected] Subject: Re: JESS: Design and Documentation of Declarative Programs (was Jess and UML) I think James Owen wrote: > JavaDoc ... XML ... Perl script ... chapter 20 in JIA book All worthy ideas, but I should point out the "official" mechanism, the "documentation comment", which every Jess rule, function, template, etc. can have: (defrule rule-name "This is a documentation comment. It can contain arbitary text and span multiple lines." ... These comments get stored in the Java representation of the Jess construct and are available at runtime via a method named "getDocstring()" in the Defrule, Deftemplate, Deffunction, etc, classes. So you can use the Jess parser to parse Jess code, then ask each construct for its own documentation. --------------------------------------------------------- Ernest Friedman-Hill Advanced Software Research Phone: (925) 294-2154 Sandia National Labs FAX: (925) 294-2234 PO Box 969, MS 9012 [EMAIL PROTECTED] Livermore, CA 94550 http://herzberg.ca.sandia.gov -------------------------------------------------------------------- To unsubscribe, send the words 'unsubscribe jess-users [EMAIL PROTECTED]' in the BODY of a message to [EMAIL PROTECTED], NOT to the list (use your own address!) List problems? Notify [EMAIL PROTECTED] -------------------------------------------------------------------- -------------------------------------------------------------------- To unsubscribe, send the words 'unsubscribe jess-users [EMAIL PROTECTED]' in the BODY of a message to [EMAIL PROTECTED], NOT to the list (use your own address!) List problems? Notify [EMAIL PROTECTED] --------------------------------------------------------------------
