The Almost Complete Reference Guide

Parts I-V

(almost - doesn't include javadoc pages for bde2java)

Final Report - Part I

Documentation for bde2java Prog. Ref. Guide I: Final Report

Programming Guide Development for Java Bde (bde2java)
Programming Reference Guide Part I

Final Report

91.523 - bde2java project - fall '96

Wing-Kin AU, Jie Li, Aditya Vedula, Li Fu Wang,
Zhigang Wang, Guillermo Zeballos

University of Massachusetts, Lowell

(path:[an error occurred while processing this directive] file:TotGuide.shtml)

Abstract

This project consists of the creation of project development documentation for future projects on the bde2java platform. This is fairly new code that has been ported from the original C++ version (worked to version 10, operating on 9 as of this writing). Development on this project would be aided by programming reference manuals that can be provided using the javadoc facilities provided by the java development kit (java jdk). We would also like to add to this documentation by including state models for the operation of the java version of bde (hence javaBde)and a coding standard to help maintain consistency with later doc builds and code updates.

Report Contents

1. Introduction

The main focus of this project was to address a problem that appears to be fundamental to the legacy code itself and that is a lack of an adequate guide for coding developments. The documentation work for most of the projects has often focused on the development of user manuals, not reference manuals for the actual code involved. The most technical user manual developed is that for chgen. This is, however, more relevant as a programming reference for any one using code generated by chgen, not so much chgen itself.

The state of the current bde2java code is not dissimilar to that of the other project documents. It also has a user guide. It does have a generation of programming reference developed from the javadoc facility provided by the javadoc development kit (jdk).

The jdk's javadoc facility for automatic code documentation provides a ready method for creating such programming reference guides without specific authoring by the programmers involved. It does this by using special comment character sequences (/** comment */)to generate html documents that are hyperlinked to each other. Each html documentc contains a wealth of information regarding the class described within the file and its methods and variables. It also creates handy class, method, and variable indexing.

All these features do depend on the commenting practices of the programmers involved. If the code is not properly commented then the documentation files are empty and essentially meaningless. This was to a considerable extent a problem with the current version of javaBde. It appeared necessary to improve the state of commenting within the document to improve the quality of the javadoc build. Also, in order for this documentation to be built over time properly, it is necessary that developers adhere to a coding standard. None had previously been defined. Also, the information that could be gleanned from inspection of the code to provide the additional documentation could be used to provide other detail information. This was used as the basis on developing state models for javaBde.

2. Project Outline

2.1 Summary of Previous Work

• The idea behind the current project was the desire to create some sort of extension to the bde2java project that was started in spring of '96 (96s523). This initial proposal was to create a bdeviewer applet with java. Our initial thoughts were to test out ideas for perhaps extending some editing functions. This had actually been done over the summer (96su523/bde2java) as a continuation by the 96s523/bde2java team. This work was deposited within $case/96su523 by the end of September. It consisted of the viewer applet and a frame that supports a java editor. While this was not a distributed editor, the creation of a distributed editor is a final goal for development of the java port of bde.

Initial attempts to develop a new project for bde2java snagged on the following points:

  1. The executables were generated with java code so it was necessary to be able to run java to see anything. Due to the local system problems this proved extremely difficult locally.
  2. The documentation also seems to present problems regarding necessary java compatability (workstations appeared to present blank pages). It was possible to see it with a PC, but this requires the directory to be visible to the http server - $case was not (at least not initially).
  3. When the files were available, the javadoc generated documents proved to have insufficient documentation of the code of bde to provide much information. The original team had both a) dissolved and b) were extremely busy.

This last point pointed out a possible direction. It was felt that if the work required to understand this code could be properly documented, it could itself represent a valid project.

Any future development requires properly documented code that could generate meaningful information after a javadoc build,– a coding standard that could help maintain clarity and the integrity of future doc builds, and– an overview of the components as a whole - namely a development of the state diagram of the system.

2.2 Goals

•Thus the main goal for the project was to develop a programmer’s guide (as opposed to a user’s guide). • With such a tool it would be possible to facilitate development of future projects and decrease start up time. This was to be done by gathering an understanding of program structure and making amendments to the current documentation (both in java doc and inline comments) and by mapping the functional states of this bde implementation. Combining this knowledge into one repository would provide the guide.

Development of a coding standard as part of this reference would also add to the consistency of future work as well as the consistency of work within the group.

One of the group members was already working on a separate project to develop a postscript printer for javaBde. It was felt that it would be best if he were also attached to this group, though he would work on his main problem, the postscript printer, mostly independently. The sole binding obligation he had to the group itself was the need to develop his code to the coding standard that would be developed. This yields the only specific executable associated with this project.

2.3 Documentation

Documentation was the whole point of the project. The main documents to be developed would be those resulting from the javadoc build. It is hoped that they be maintained at a high level in the current project directories for ease of access as an html document. As of this writing it is proposed that the current files will be moved to "$CASE/96f523/bde2java/doc" although currently permissions have not been set for the move. All the necessary files should currently reside alongside this one in this current directory path [an error occurred while processing this directive].

The actual documents are:

With the exception of the last section, one could consider each as part of a larger programming reference guide. The files are being written as *.shtml files to provide more flexibility in hardcopy builds by permitting the use of server side includes (see the Server Side Include page referenced above for usage of <--!command modifier--> tag).

3. Project Development

Initial development will required that we quickly learn and understand java code. This was to be based on our own previous experience with previous languages as none of us at the time has specific knowledge of the java language. In order to plan out the time requirements for this project (time being the constraint), separate files were selected to gather some data on possible learning curve times. The files selected were those javaBde documents of medium to large size located away from the leaves of the class hierarchy. It was felt that these would provide a higher overview of the operation of the methods and purposes of classes.

3.1 Initial Task Plans

Initial suggestions were for the development of rather substantial and complete guides that would have comparison to original code as well as development of test suites. • The purpose of this plan was to allow parallel development of both javaBde and the C++ version of bde. This was based on certain knowledge that differences must exist. Even though the java version was built off the code of the C++ version, this was a hand coded job and not part of the chgen tool.

It was also hoped that the object oriented nature of java would allow better object oriented development for bde. It was in a sense assumend that it would be more likely that bde would probably be made to emulate javaBde more than the other way around. It might even be possible, given sufficient parallelism, to tailor chgen to generate the necessary java routines for future java chgen projects.

After an initial week and a half of code review it was observed that the learning curve times were considerably worse than expected. A decision had to be made with regard to what was to be accomplished and it was decided best to focus efforts on the javaBde code itself rather than divide our efforts with understanding how it related to bde and chgen.

3.2 Task Division•

After initial immersion in files, it was felt that work be divided between the need to produce: –

The first task was assigned to three team members who were given the flexibility to plan out their own review strategy. They basically divided the existing code about logical class boundaries so as to maintain a better sense of context to the way the available methods were implemented.

The second task was divided over two team members. This required a similar kind of code review to that of the other three, but differed in what was actually being identified. Using the state.h file as an initial set of defined states, the code was reviewed to identify a consistent method by which control flow was managed. A GUI graph editor being particularly dependent on events, special attention was placed on branches on events and event state variables.

The last task was principally the job of one team member who was carrying over the task from a previous project. His initial task of completing a postscript printing facility for javaBde was maintained and added to. It was now also necessary for him to meet requirements of the new coding standard. It was hoped that any problems with the coding standards would come to light as a result allowing changes to be made before the end of the project.

4. Project Observations

This section is meant to briefly note some observations for the future developer so that they may not be surprised by what they may find.

The code initially contained many typos and cut and paste errors in the commentaries. This resulted in a certain amount of misunderstanding. Wherever this kind of error was spotted, it should have been corrected. Still there is reason to suspect that some methods may not be currently be active or may be redundant. The reasons for this may have been because their use was planned and not implemented, or the methods were supplanted by other methods that may have initially been experimental (so the originals were not simply replaced) and simply left behind. This is because some operations, for instance TextCaption operations seem to occur over various methods doing apparently ovelapping tasks. As of this writing it has not been determined if this is indeed the case or not for this example.

The code is at this point in time not by any means parallel to bde. The lack of a header file results in a different treatment of states than that given by bde. Many preconditions are defined at the time of implementation by checking the condition of various flags - sometimes in conjunction. There are also event variables in java that are used to control the flow of operation, but these are not used exclusively. Another problem is the use of extrememely long path names for some variables. These are often placed in if statement condition expressions and prove to be so long as to result in the actual condition being printed off the page. This makes it extremely difficult to figure out what is going on. It is requested as part of the coding standard that program width be limited to 80 columns (unfortunately the limit of available printers in CS).

Code review can indeed be an exercise in reverse engineering. The amount of time required to backtrack the functionality of code purely by inspection should not by any means be underestimated. In some cases it is probably much longer than the time it took to write. After a huge investment of man hours into code review, it is apparent that it is still extremely difficult to get more than a high level impression of most of the methods within a class.

It is hoped that this last point be particularly taken into consideration by future projects.

5. Project Tasks

5.1 Completed Subtasks

The main thrust to complete revamped class header comments and method header comments was nearly completed. This effort was directed at discovering the nature of classes and methods and fill in the many blank header comment boxes that were already extant. The coding standard specifies that the header comment be designed in such a way as to be consistent with the usage of javadoc to build a new reference document. As of this writing, the build process is underway and should result in a new javadoc for bde2java resident within its current cvs repository.

Another task that should be completed is a recompilation of the code to verify and/or ascertain if any bugs have crept in as a result of added comments. At no time were any executable expressions modified or appended to. The only executable expressions were those pertinent to the development of the postscript printing facility (below).

The analysis of the states of javaBde was made to the point were some initial state diagrams could be made illustrating its operation. An inspection of the code in the methods involved appear to indicate that some of these diagrams are incomplete pictures of what is actually occurring within those functions. Documentation for this initial inspection is provided.

The postscript printing facility has been completed and to our understanding even demonstrated. It has been checked into the cvs repository with the current version of bde2java and should be added to the final java doc build with its code up to the new standard.

5.2 Problem Tasks

The initial plan to carry out a complete comparison of javaBde's states with the state definitions within bde is not feasable at this time. The method by which javaBde carries out control is clearly different and not immediately comparable. The analysis of the states themselves is itself rather shallow. While within methods one can track transitions on the event variables used, from method call to method call, it is more difficult to see and illustrate the entry conditions (as defined within the code) from methods in different classes. It would perhaps be best to treat transition as based on a chain of variable values. This would require deeper focus on the classes that do implement what appear to be the critical switch statements (such as bdeGraph.java).

The current complexity of the code (even at this early age) makes it impossible to bring any of the internal code documentation up to the currently proposed standard. The current standard requires extensive documentation of used variables and branches which at the present moment in time cannot be identified in their entirety. As a result the additional commentary are intended to focus on improved javadoc built reference guides.

–

5.3 Example of Task

Deriving understanding of code for sections and method descriptions:

In the beginning the code that we were dealing with could typically be something like the following. A particularly poorly documented piece of code was that for the action() method in bdeGraphBox.java: 

    public boolean action(Event evt, Object arg)
    {
        System.out.println(" evt: " + evt + " arg: " + arg);

        if(evt.target == OKbutton)
        {
            System.out.println(" 2 ab");

            if(parentApplet.tb.UpperCheckBoxIndex == parentApplet.tb.GRAPH)
            {
                parentGraph.Create(txt.getText()); 
            }

This is not typical of a section of code of the bde2java application as deposited in September. Most did indeed have header comment blocks. These blocks were mostly empty, containing only the name of the method and its corresponding class (and not always correctly. None of the comments within such blocks of code has been designated to appear in a javadoc build. Those require the use of "/**...*/". The long line of asterisks with which the delimeters for the blocs were constructed did not actually trigger it as it ignores anything greater than 2 * in a row. Even without a javadoc comment of any kind, this code would still generate a mimimal javadoc reference material. (Note for brevity the material is edited, focusing only on that which pertains to the method in action() question).

The resulting javadoc build would have very scarce information about the method other than the method name and type in its argument and the class it belongs to. No mention would be made of its purpose, preconditions, postconditions, etc., not even what it returns. You can now compare this to the same method after it was reviewed and given a new comment header block: 

 /* ***************************************************************/
 /**   
 * <PRE> * Method       : action()
 * Description  : Excute actions on the selected object
 * State info   : evt.targe = OKbutton { if Graph --> Create Graph
 *                          if Text  --> Create Graph Caption Text
 *                                 } --> set status flag to ACTION_OK.
 * Class        : GraphBox
 * </PRE>
 * @param evt evt.id
 * @param arg selected object
 * @return true or false
 *
 */
 /* ***************************************************************/
 public boolean action(Event evt, Object arg)
  {
     System.out.println("evt: " + evt + " arg: " + arg);

     if(evt.target == OKbutton)
       {
       System.out.println(" 2 ab");
       if(parentApplet.tb.UpperCheckBoxIndex == parentApplet.tb.GRAPH)
         {

The header block delimeters are designed to not affect the formatting of the javadoc information. Note the usage of special tags to preformat the way information is presented. The @tags present additional information in the method description. The effect this had on the resulting javadoc reference page is shown below.

The javadoc Development Report contains another example of a javadoc build comparison before and after comment modifications. The reader may wish to refer to this and the Coding Standard for help in maintaining the bde2java javadoc reference pages. (See Section 2.3.1 Programming Guide Document Hierarchy for link or file location information)

Future Work•

Project Continuation

The basic and fundamental reason for this project was to provide a usable programming reference tool for future develoment in java. The use of javadoc makes it simple to maintain an updated version of programming references with each new project. Still due to the lack of detailed documentation of the inner workings of the code, it would be good if additional reviews be made to bring more of the code up to the documentation standard. The collection of references should also be made to work as a more cohesive comprehensive document (maybe in a well designed hypertext context)

It may be more reasonable to ask that back commenting to standard be part of any work that results in direct handling of methods already written. Since the programmer(s) involved would already need to become very familiar with that particular piece of code, it should remain as a relatively simple task to carry out.

Another possibility would be to begin some back inspection and review for the purpose of creating programming reference guides for the non-java project code. This may be easier to carry out since most students may be more familiar with C and C++ than java. The legacy code also should be relatively well documented internally as some is the result of chgen and much of it has been reviewed for quality as well even if it is possibly more complex. Once a more complete set of programming reference guides are available, project start-up times may be improved.

An analysis of the operational states based on interface events (separate from flag variables) may help establish a clearer picture for the actual state model for javaBde. Even though it would not represent the actual values of various flags, it will record necessary preconditions to carry out actions. These can then be checked to the sequence of flag values that carried out the operations.

The java guide should not be static, but should be revised and updated as more is written and clarified. Whether this is done as a specific project or part of ongoing development will probably need to be determined on the basis of project weight.

Project Extensions

The following are mentioned as extensions as opposed to expansion in that while they may serve the purpose of making the code more understandable and usable, the means and aims of what needs to be done are slightly different from this project's. This project maintained for the most part a healthy distance from actually changing the way anything really worked.•

As mentioned previously, there do appear to be inconsistencies regarding some method definitions. There are also considerable amounts of commented out code. A real issue is whether or not these pieces of code are necessary or not, or just debugging lines needs to be determined. If they are indeed extranous they should be removed. If they are an emergency patch or a very obscure call, they need to identified. This requires actively changing executable expressions of the code - something we as a team aggreed we would not do. We did recognize that for the purpose of future clarity, this would be a necessary part of making the code more accessible for future development.

There was at some point some question about bde2java's stability. At this point, with the exception of one bug, seems to have been a jdk version problem. The one bug that does appear involves the drawing of one of the links over nodes on occasion. This may have been fixed in a newer version that is currently not resident within $case. The nature of this error and its fix may need to be tracked down (back to the author?). Other possible bugs do probably linger within it.

The original proposal to observe the similarities and differences between the C++ version and the Java version of bde may yield considerable documented insight into both. It makes sense that if the two can be made more alike, future builds on one would be easaly portable to the other. This may also apply to builds of reference guides to the original (given java's automated ones).

Suggestions for future work

Future work on development of bde2java projects may wish to focus on the host of functionality currently identified as not-implemented. The actual methods not implemented should now be more clearly identified. Rather than just deal with the knowledge of missing functionality, one may find the actual class location where these functions are giving some insight in the original plans for their use.

Suitable test suites should be developed to put the program through its paces. This can be more easaly done once a good understanding of its functional states is developed.

A java version of chgen has also been proposed. The only function that is apparently replicated in bde2java appears to be pr_dump. Perhaps a javaChgen may result in an improvement in new project development using java for 91.523 projects.

Ultimately, the final goal is to develop a distributed block diagram editor. Distributed editing is not a trivial task but should prove interesting. It should only be the result of an incremental build. It may perhaps be best to simply start with a toybde editor before moving up to the full version.

The reasoning behind the last remark goes as a caveat for reading developers that

With that said, it is hoped that this train of development may continue to be fruitful as, given the current code size of the original projects, this may be among the more practical choices for those with the resources.

91.523 - Software Engineering Project - · - 96f523 - bde2java

[an error occurred while processing this directive]/TotGuide.shtml
Last updated: Friday, 20-Dec-1996 21:32:20 EST

State Models - Part II

Documentation for bde2java Prog. Ref. Guide II: State Models

Programming Guide Development for Java Bde (bde2java)
Programming Reference Guide Part II

State Machine Models for bde2java Implementation

91.523 - bde2java project - fall '96 - UMass Lowell

Jie Li, Guillermo Zeballos
bde2java team: Wing-Kin Au, Jie Li, Aditya Vedula, Li Fu Wang, Zhigang Wang, Guillermo Zeballos

Edition: 1.0
(path:[an error occurred while processing this directive] file:TotGuide.shtml)

1. Introduction

The following is a summary description using state models of some of the operations in bde2java or javaBde. The diagrams are modeled after standard FA notation. The purpose of this type of documentation is to support the documentation supplied by the javadoc facility. While the javadoc facility provides a means of defining code elements, it is not necessaraly representative of its operation. It is hoped that the creation and maintenance of this document will permit greater understanding for future developers of javaBde.

1.1 Document Layout

The document is organized around a graphical representation of the some of the operations within javaBde. Each figure is followed by explanatory text. Paths to original idraw images are to be stated.

Following this section will be a textual analysis of the states. This differs in being more an identification of the branching conditions within the class methods defined in javaBde.

This text will only refer to "some" operations because as of the time of this writing it cannot be claimed that a complete picture of the states and transition rules of for javaBDE can be drawn. It is also to identify a single alphabet on which to define transition rules as pre-conditions are not necessaraly identified and assigned to any one variable. It is often the case that method calls and actions are set into motion by identification of several conditions (such as if (cond1 && cond2 && cond3)). Many of the rules for transitions are located in specific methods and not readaly available as case statements.

1.2 Machine Descriptions:

Machines were described using finite state machine notation. Strict interpretation of these models is not recommended as they describe operations over class definitions, almost as if the class definitions themselves are representative of a higher level state definition. This is not the case with the current implementation. While a common entry is defined, it is only meant to represent that the transitions described will only be pertinent to the states of one particular flag variable (the alphabet). Interpretation of the notation at this point should be flexible as they are more representative of the structures of classes.

These descriptions could be expanded upon if a clearer description of the preconditions for entry to a particular method of a class be better defined. Figure 2 comes closest to illustrating the event cycle that defines the process. It is hoped that this will be done in future work and this document will accordingly be ammended.

2. Operation Descriptions:

Fig.1 - Fundamental Modes for bde2java

/usr/proj3/case/96f523/bde2java/gzeballo/idraw/state1.idraw
This figure illustrates the current basic modes of operation for bde2java. The modes of operations are identified within the class bde2JavaApplet , and more specifically the methods init() and init1(). The flag variables used are nAppletMode and JavaMode

Breakdown of states:

  1. Stand alone application: Operating as Graph Editor
  2. Browser Applet: Operates as graph viewer

Fig.2 - bde2java Event Handling Outline

/usr/proj3/case/96f523/bde2java/gzeballo/idraw/bdeOutline.idraw
This figure is meant to illustrate the event handling loop as it appears to be implemented within bde2java. It is not specific to any one class definition. Its basic operation is based on detecting any mouse event. The event handler verifies if Event=ACTION() or evt.id=MouseUp || MouseDown || MouseDrag. If it is Event=ACTION() then it is checked as an action over the UpperCaseBox (UCB) or the LowerCaseBox(LCB). The respective box is highlighted and selection flagged. The process then loops back to await another event.

If it is an event setting evt.id to the above states, then Navigator checks to see if it is a node hotspot event. If so it will print out a new graph and then reinitialize that graph before returning to an event wait state.

Non hotspot events are then passed to an event handler that determines whether UpperCheckBoxSelect(US) is on (=1) and then check if LowerCheckBoxSelect(LS) is on (=1). If both are true event is handled otherwise it loops back to wait event. After event is handled process loops back to wait event.

Fig.3 - Graph Operations

/usr/proj3/case/96f523/bde2java/gzeballo/idraw/bdeGraph.idraw
This figure illustrates current understanding of the operation for methods within the bdeNode.java class over the possible values of the variable evt.id. It also contains the handling of the switch over the value of UpperCheckBoxIndex.

The most important operation within this class appears to be that within StateSelector as it appears to be the closest parallel to the original bde's case switch on state. It switches on the operation of the value of UpperCheckBoxIndex which can take on the following values: 

      NODE:       call nodeFunction()
      LINK:       call linkFunction()
      TEXT:       call textFunction()
      BENDPOINT:  call bendpointFunction()
      GRAPH:      call graphFunction()
      CAPTION:    call captionFunction()
      DEFAULT:    print error message.

Fig.4 - Node Operations

/usr/proj3/case/96f523/bde2java/gzeballo/idraw/bdeNode.idraw
This figure illustrates current understanding of the operation for methods within the bdeNode.java class over the possible values of the variable evt.id.

Two points of note: 1) that within Delete, a branching condition exists on deletion based on whether or not the mouse is currently over the selected node when the Mouse Up event occurs. 2) that within Restyle, the process of restyling is controlled by whether the current node is the first or second node selected.

Fig.5 - Link Operations

/usr/proj3/case/96f523/bde2java/gzeballo/idraw/bdeLink.idraw
This figure illustrates current understanding for the operation for methods within the bdeLink.java class over the possible values of the variable evt.id. The point to note here is that in the method Create, selection of the second node after the Mouse Drag event only occurs mouse is actually over a different node.

Fig.6 - Bend Point Operations

/usr/proj3/case/96f523/bde2java/gzeballo/idraw/bdeBendPoint.idraw
This figure illustrates current understanding for the operation for methods within the bdeBendPoint.java class over the possible values of the variable evt.id.

Create requires existing link. Restyle allows for 3 different kinds of styles.

Fig.7 - Graph Caption Operations

/usr/proj3/case/96f523/bde2java/gzeballo/idraw/bdeGraphCaption.idraw
This figure illustrates current understanding for the operation for methods within the bdeGraphCaption.java class over the possible values of the variable evt.id.

Fig.8 - Text Operations

/usr/proj3/case/96f523/bde2java/gzeballo/idraw/bdeText.idraw
This figure illustrates current understanding for the operation for methods within the bdeText.java class over the possible values of the variable evt.id.

Text operations within the bdeText.java class are somewhat involved in that they operate over GraphCaptionText, CaptionText, and Node. Also Create involves the operation of GraphBox, but whether it returns from Graph Box was not clear.

Additional remards: Move() contains branching to select if movement involves node (set node selected), or GraphCaptionText (set graphCaptionText selected), or neither(return) Delete3() operates strictly over CaptionText. Delete() over node or GraphCaptionText by branching whether one or the other is selected.

Fig. 9 - Some Java Operations

/usr/proj3/case/96f523/bde2java/gzeballo/idraw/javaOps.idraw
This figure is included to illustrate some java operations that also operate over the two often used variables evt.id and evt.target. They also contain different values. The developer should take not of the range of values for these two.

3. Additional Descriptions

The following text is based on an analysis of the branching operations within methods. It is from this same analysis that the above figures were derived. What follows is the textual description of operations not illustrated as pseudocode. This is because it was not clear how their operation fitted in with the operation of other methods and the variety of different methods make tracking transition rules difficult. An example of the last case is bde2JavaApplet where many operations happen on a variety of flags making it hard to define a common language on which to define transitions (on evt.id, or nAppletMode, or evt.target?)

Hopefully the tracking of mouse events illustrated in the "Event Handling Outline" figure should act as guidance with respect to transition on events.

(excerpted from $case/96f523/bde2java/jli/state.3) 

1. DisplayFrame.java:
   Method: handleEvent()
   evt.target = scrollbarV --> get offset Y --> repaint;
   evt.target = scrollbarH --> get offset X --> repaint.

2. bdeAppletFrame.java:
   Method: handleEvent()
   evt.target = MenuItem {Exit  --> exit system;
                          New   --> not implemented;
                          Print --> print PS file;
                          Open  --> read in a bde data file and show 
                                    on the Applet Frame;
                          Save  --> save file to current filename;
                          Save As   --> save file to the filename specified;
                          About BDE --> print bde message;
                          }

3. bde2JavaApplet.java: 
   Method: handleEvent()
   evt.target = Graphlist --> get GraphName --> repaint the Graph.
   // this is a (choice) java event. The choice items are graph names.     
   // Selecting one choice item will make corresponding graph painted.  -jie

   evt.id = WINDOW_DESTROY{if inApplet --> dispose the window;
                           else        --> exit system;
                          }
 
4.  bdeToolBox.java
    Method: handleEvent()
    evt.target = NODE      --> show node related attributes
    evt.target = LINK      --> show link related attributes
    evt.target = TEXT      --> show text related attributes
    evt.target = BENDPOINT --> show bendpoint related attributes
    evt.target = GRAPH     --> show graph related attributes
    evt.target = CAPTION   --> show caption related attributes
 
5.  bdeGraphSelectionBox.java:
    evt.target = OKbutton --> set flag from ACTION_PENDING to ACTION_OK.    
    evt.id = Event.WINDOW_DESTROY --> hide window and set flag to
                                      ACTION_CANCEL
 


6.  bdeNodeAttributesBox.java
    Method: action()    // the action clears OK button
    evt.target = OKbutton --> hide the OK_button
                              set status = ACTION_OK

    Method: handleEvent()
    evt.id = WINDOW_DESTORY --> hide window

7.  menutest.java
    Method: mouseEnter() --> set bSelected = true in terms of mouse (x,y)
                             repaint

    Method: mouseExit() --> set bSelected = false in terms of mouse (x,y)
                            repaint

    Method: mouseDown() --> set nSelectedNode = -1
                            reaint
        // i.e. set nSelectedNode = NOT_FOUND (file: bdeRefrence.java)

    Method: mouseUp()   --> set bMouseDown = false
                            repaint

    Method: mousedrag() --> set bdeMouseItemText = "Test"
                            repaint
                            set bMouseDown = true
For a full listing consult the files $case/96f523/bde2java/jli/state.1, and $case/96f523/bde2java/jli/state.3.

4. Final Comments on Section

The model needs an improved definition of the pre-conditions regarding entry into the functional operational modes of javaBde. Currently the handling of some events passed to evt.id and evt.target have been identified, but there are other variables that need to be checked such as selectObject.selected of which there are various.

A seperate analysis of operational states only from the interface (as opposed to the way the method calls are implemented) may help in more clearly identifying the flags used to verify preconditions before executing an operation.

Finally, it is hoped that test suites can be developed from the information gathered from these references.

5. A Note on this Document's Figures

The figures in this document were created using the idraw (interviews graph editor) application to generate the original diagrams as *.idraw files. The images were "grabbed" from their application window using the xv(v.3.01) application, cropped to fit the page, and then saved under the local gif's directory as gif files. Updating of this document will require a similar process.

91.523 - Software Engineering Project - · - 96f523 - bde2java

[an error occurred while processing this directive]/TotGuide.shtml
Last updated: Friday, 20-Dec-1996 21:32:20 EST

Coding Standard - Part III

Documentation for bde2java Prog. Ref. Guide II: Coding Standard

Programming Guide Development for Java Bde (bde2java)
Programming Reference Guide Part III

Coding Standard for BDE2JAVA
1.0

91.523 - java2bde project - Fall '96
Win-Kin Au, Jie Li, Aditya Vedula, Li Fu Wang, Zhigang Wang, Guillermo Zeballos

University of Massachusetts, Lowell

(path:[an error occurred while processing this directive] file:TotGuide.shtml)

These are the coding standards for usage in bde2java project development. They were derived by mutual consent and discussion by the bde2java team, 96f523.

1. Variables:

All variables are as defined in standard Java definition.

All variables must have descriptive names.

All variables need brief inline descriptive comments.

2. Constants:

All constant names should be capitalized.

3. Naming Conventions:

The following conventions apply to all naming situations unless otherwise specified or superseded by specific conventions defined in type description (i.e. Constants, Variables).

Abbreviations should be avoided whenever possible. It is recommended that some abbreviations be referenced from a table of standard abbreviations to maintain variable naming consistency when abbreviations are used.

Names should be descriptive of functional purpose.

All class naming must be preceded by the word "bde" in lower case. The first letter after "bde" should be capitalized. If the name is composed of multiple words, each first letter is respectively capitalized.

4. Code Documentation Conventions:

Code documentation refers to commentary to be contained within the code itself as both inline comments and as part of the javadoc build comments. This not a specification for other types of documentation (final reports, user guides, etc.).

4.1 In General

Comments must address the following:

4.2 Javadoc Specific

5. Coding Conventions:

All class and method definitions will contain the necessary javadoc build comments compatible with current java style documentation for java doc (as per previous section).

Standard indentation rules denoting bracket nesting should be practiced. The programmer should make an effort, however, to try to maintain the code to within 80 columns due to the difficulty in generating wide margin output.

Only one class should be defined per file. Files will need to be maintained in the file hierarchy as required by the java environment.

Code examples follow.

5.1 Header Block Example:

For Class description

/* ****************************************************************/
/**
*
*       Class: Class name 
*
*       Description: Text Description (per commenting requirements)
*/
/* *****************************************************************/
subsequent code...

For Method description (note slight indent)

   /* ****************************************************************/
   /**
   *
   *       Method:(public|private)(return value)(Method name)(parameter list)
   *
   *       Description: Text Description in full 
   *                    - pre & post conditions 
   *                    -side effects
   *
   *       State: any key state (control) variables
   *
   *       Class: Encapsulating Class name
   *
   *       @param parameter details
   *       @returnreturn values
   *       @exception error exception breaks
   */
   /* *****************************************************************/
subsequent code...

Consult the javadoc Development Report(Ref. Guide part IV) listed in section 4.2 for additional support and examples of the results from a properly formatted javadoc comment.

91.523 - Software Engineering Project - · - 96f523 - bde2java

[an error occurred while processing this directive]/TotGuide.shtml
Last updated: Friday, 20-Dec-1996 21:32:20 EST

Javadoc Development Report - Part IV

Documentation for bde2java Prog. Ref. Guide IV: Javadoc Dev.

Programming Guide Development for Java Bde (bde2java)
Programming Reference Guide Part IV

bde2java Javadoc Development Subgroup Report
Reference for Javadoc Development

Wing-kin AU, Li Fu Wang, Zhigang Wang
bde2java team: Wing-Kin Au, Jie Li, Aditya Vedula, Li Fu Wang, Zhigang Wang, Guillermo Zeballos
91.523 - Software Engineering - UMass Lowell - Fall 1996

(path:[an error occurred while processing this directive] file:TotGuide.shtml)

Introduction

The main objective of this project (96f523/bde2java) was to generate documentation in javadoc style using the javadoc facility supplied by the java development kit (from javajdk ver 1.0). This document is meant to serve as a quick reference to the following issues:

  1. State of the code and work experience
  2. An example: Before and after application of new comments
  3. Quick Javadoc tutorial
  4. Instructions for compiling bde2java code
  5. Instructions for running javadoc
  6. and some compiled logged times for code review

1. State of the code and work experience

While an original generation of javadoc had been created, The original documentation had not focused on generating a complete reference guide and had not written to a specified coding standard. This made further development very hard.

The process of understanding the code has took a lot of time due to this lack of documentation. Some of the original comments did not match the real funtionality of the code. There is also a lot of unused code in the program. At least 20 out of the 200 methods are empty or are not being called. Some methods are so similar to other methods that we do not understand the reason the programmer needed to implement two seperate ones. Some of the code we are not able to understand completely. The difficulty of understanding the code is reflected in the given log files as we spent a lot of time on decoding the code itself.

We had experienced some difficulty in compiling and ruuning bde2java, again due to lack of instructions from previous project. We finally were able to compile bde2java on both PC and workstation. Though we were able to run bde2java on a PC, we still have difficulty in running bde2java from a workstation apparently due to the problems inside the interptreter of javajdk used in our CS system. For the purpose of letting other students easier in compiling and running bde2java, we have written some brief instrustions and steps that they can follow in this report (see sections 3-5)

We had found out some of the special properties of javadoc that we need to pay attention to. As a result we need to put down our code documentation in a special way.

The following is an example of the a piece of code showing the difference in javadoc before and after modification.

2. An Example: Before and after application of new comments

Before:The original java program looks like:

The output .html file looks like:

After: The comment added java program looks like this: 

       
                          .
                          .
                          .
     /* ******************************************************************/
     /** 
     * <pre> 
     * Method      : Delete()
     * Description : Delete a node, depending on mouse event, 
     *               if it has not a link
     * State       : evt.modifiers = Event.META_MASK 
     *                             --> print a message
     *               evt.id = MOUSE_DOWN 
     *                      --> select node for given (x,y)
     *                          set FirstSelectedNode.selected = true
     *               evt.id = MOUSE_UP   
     *                      --> check if current node is the same 
     *                          node as FirstSelectedNode
     *                          if yes --> delect the node, 
     *                                     update links
     *                          if no  --> set 
     *                             FirstSelectedNode.selected = false, 
     *                             return
     * Class       : bdeNode
     * </pre> 
     * @param 
     * <pre>
     * (x,y) node point
     * </pre>
     * @param 
     * <pre>
     * evt event in case of,
     *     MOUSE_DOWN, get selected node or NOT_FOUND
     *     MOUSE_UP,   if not NOT_FOUND, get number of links 
     *                 of the selected node, delete it, update
     *                 parent list, and repaint it
     * </pre>
     * @return       None
     * @exeception   None
     */
     /* ******************************************************************/
                          .
                          .
                          .

The output .html file looks like:


3. Quick Javadoc tutorial

The following is a list of javadoc tags that that are read by the facility to format the reference document. 

/* ***...*/ : tell javadoc do not pick up this line 
              (not for javadoc). For use with code delimeters.
/**         : start to convert (generate) the following 
              documentation into .html file (source_filename.html)
*/          : end of javadoc segment

<pre>...</pre>: shows everything between the tags
                literally [preformat]
                Note: Usage of "." inside the tags can
                       generate formatting errors - AVOID

@param single-string : define input paramenter 

             if you have more than one string in the documentation, 
             you have to use:
                  @param 
                  <pre>
                  paramenter_name_1 description
                  </pre>
                  @param
                  <pre>
                  paramenter_name_2 descrption        
                  </pre>

             Note: javadoc only considers the first word as the input
                   paramnter. In case of two input paramenters, two
                   @param required.
            

@return single-string : define return result
             in case of multiple returned paramenters:
                 @return
                 <pre>
                 return_name_1 return_name_2 ... (or descption)
                 </pre>

@exception single-string : define side-effect
             also, 
                 @exception 
                 <pre>
                  ....
                 </pre>
PS: @param, @return and @exception will show up in method description of
the html document

4. Instructions to compile bde2java

On a PC:

On a workstation:

Unfortunately, due to some problems existing in the interpreter of the jdk, bdeJava probably will not run. A window for bdeJava will come up for a tenth of a second and then crash. It is possible that updates to jdk may remedy the problem.

5. Instructions to run javadoc

On a PC:

On a workstation:

it will then genereate the bdeCpationText.html

6. Some compiled log times for code review

COMPILED LOGS:

Wing-kin (Steve) AU's log:

learning Java : 45 hrs

trying jdk compiler and javadoc on both platforms : 25 hrs

Understanding the code : 60 hrs

Adding comment : 30 hrs

Li Fu Wang's log:

Learning_java : 55 hrs

Understanding the code : 50 hrs

Addng comment : 50 hrs

Zhigang Wang's log:

Learning Java : 55 hrs

Understanding the code : 50 hrs

Adding comment : 55 hrs

DOCUMENTATION SUBGROUP TOTAL HRS: 480 man hrs.

This reflects time spent over the semester development period.

91.523 - Software Engineering Project - · - 96f523 - bde2java

[an error occurred while processing this directive]/TotGuide.shtml
Last updated: Friday, 20-Dec-1996 21:32:20 EST

Javadoc Listing - Part V

BDE2JAV1 Web Page

Programming Guide Development for Java Bde (bde2java)
Programming Reference Guide Part V

Link Tree to Current Javadoc Build for bde2java

University of Massachusetts - Lowell

Professor Dr. Robert Lechner

Wing-kin AU, Jie Li, Aditya Vedula, Li Fu Wang
Zhiang Wang, Guillermo Zeballos


This page consists of the work done by the team members of bde2java fall 96' team.

BDE stands for Block Diagram Editor. The bde project is one of the many CASE tools created by graduate students in the computer science deptment. All projects are managed by Professor Dr. Lechner.

The following is the list of bde2java's classes as generated by the javadoc utility

91.523 - Software Engineering Project - · - 96f523 - bde2java

[an error occurred while processing this directive]/TotGuide.shtml
Last updated: Friday, 20-Dec-1996 21:32:20 EST