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:FinalReport.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]/FinalReport.shtml
Last updated: Friday, 20-Dec-1996 21:27:00 EST