In this article we'll examine reusability and its benefits, and we'll provide some advice on how developers can transform a good mathlet into a great one through coding guidelines and software engineering techniques. We'll present the results of an analysis of the mathlets that appear in the inagural issue of JOMA and discuss responses to a mathlet developer survey. In a future article we'll go into depth on some of the techniques we present here.

Mark Chung is a software engineer with SRI International. Chris DiGiano is a Senior Research Computer Scientist with SRI International. Both are active in the ESCOT Project.

We can offer a perspective based on our experience of developing forty applets for middle school math -- these applets were hosted by the MathForum over the last two years. With that many applets to develop, we were keen to develop techniques for reusing our own code and that of others rather than developing each one from scratch.

Published April, 2002

© 2002 by Mark Chung and Chris DiGiano

The software engineering literature identifies many kinds of reuse [Leach, 1997], but for our purposes we will focus on three kinds:

1. Application reuse (you as product vendor to teachers): A teacher may want to reuse your mathlet by customizing the text or tweaking the behavior to produce an alternate lesson. Similarly, a content provider may want to integrate your mathlet into an online assessment or class. You can't anticipate all the possible uses for your mathlet, so it makes sense to build in enough flexibility to accommodate a reasonable range of uses. We will call this kind of reuse application reuse.

    

2. Designing for reuse (you as producer of code for developers): A third party developer may want to reuse your mathlet by using it or its associated library to develop another mathlet. It wasn't surprising to us to see that the first mathlets featured in JOMA almost all had graphers and that they each used their own implementation. By designing for reuse, you make it easier to reuse your own code, and if you decide to release your source code or binaries, you increase the likelihood of adoption by other developers. This could eventually lead to improved software quality and longevity, because those developers may provide feedback and patches [Raymond, 1999].

    

3. Code reuse (you as consumer of code from developers): You may want to reuse existing code to speed up your development. This avoids duplication of effort and, if you use an established library, may increase reliability and reduce debugging.

These reuse practices are summarized in the following table:

Given all those benefits, why doesn't everyone engage in reuse? First, designing for reuse costs more than not designing for reuse, because it takes more effort to design and develop code that works outside of a specific application and to create associated documentation and tests. However, much of this effort should be considered good programming style, and the effort will pay off when you reuse your own code. Second, the code may be a trivial implementation or a toy example in which designing for reuse would consume most of the coding effort.

There are also some issues when reusing code. First, the code you may want to reuse may have a licensing policy you disagree with or may be prohibitively expensive. Second, it takes effort to find suitable code to reuse, select when there is more than one candidate, and understand the code. Third, there's the educational value of coding it yourself. You may not want to reuse code if you're teaching yourself to program. However, most professional programmers today reuse code whenever they can.

Analysis

We did an analysis of the mathlets in the inaugural issue of JOMA to examine their reuse characteristics. Of the ten mathlets, three were server side applications with a web interface and seven were Java applets. For the purposes of this article we will focus only on the applets:

Here's an example of how customization could be useful. The graphing applets offer much flexibility, but it might be difficult or impossible to configure them to launch with a pre-specified function. This would be useful, for example, in online assessment. In addition, it may be useful in that context to be able to selectively hide portions of the user interface, for example, whether the function definition is displayed.
Only one of the applet developers provided source and documentation (Tom Leathrum's Generating Tables to Demonstrate Limits), and another offered it by request.

Most of the applets used common GUI (graphic user interface) widgets found in the Java 1.1 AWT (Abstract Windowing Toolkit), such as buttons and text fields. Some had slightly unconventional user interfaces. Consistency of behavior becomes an issue when aggregating mathlets into large collections.

Survey

In addition to our analysis, we surveyed developers of the first JOMA mathlets to find out if and how reuse played a role in their programming.

Two of the four respondents were concerned with application reuse; one provided applet parameters as a solution.

Two developers reported they were learning Java, which for one of them meant coding largely from scratch for the educational benefit. Developers who were building larger collections of mathlets were reusing their own code and designing for reuse, including designing APIs to allow customization or communication with other tools. One developed standard frameworks that could contain various kinds of learning content. Developers gave reasons for not releasing source code including discomfort with having their code scrutinized closely and the desire to protect intellectual property.

Two developers expressed an interest in interoperability, that is, exchanging data with other software. The types of software mentioned included online testing, e-books, computer algebra systems (CAS), dynamic geometry, physical sensors. They both have explored exchanging data with a CAS server. One converted his applet into a JavaBean and experimented with interoperability with other beans in an application builder environment. We will cover interoperability in our next article.

Separate text from the mathlet

In our experience we've found that teachers often want to customize the text in a mathlet. When we first started developing problems of the week for MathForum we embedded the text inside the interactive activity (for reasons related to our deployment strategy). This made it difficult for end users to modify. Our problems of the week now ship as applets embedded in a web page containing the instructional text, so it is easy to modify with an HTML editor. So the first technique is to separate the text from the mathlet so it is easy to customize. We found that the JOMA mathlets all used this technique. Separation of text is also important for internationalization, although other programming techniques are necessary to internationalize and localize UI text (e.g. the java.util.ResourceBundle class in Java 1.1).

Parameterization

Teachers may want to change the behavior of an mathlet without programming or hiring a programmer. An easy way to enable this in Java is to provide a set of applet parameters to configure your applet. The parameters -- key value pairs -- are set in the HTML tags for the applet and are made accessible to your applet through the applet API.

A good example of this is Bert Wachsmuth's Integrator applet, featured in JOMA Volume 1, Issue 1, which computes Riemann sums for a given function. All of the user-visible and user-adjustable parameters are configurable via applet parameters.  By doing View Source in the browser you can see what the APPLET tag looks like:

             <APPLET CODE="ira.integrate.Integrator.class"
                          WIDTH=420
                          HEIGHT=320>
                   <PARAM NAME="function" VALUE="sin (x)">
                   <PARAM NAME="xmin" VALUE="-3.14">
                   <PARAM NAME="xmax" VALUE "3.14">
                   <PARAM NAME="numpoints" VALUE="20">
                   <PARAM NAME="rightsum" VALUE="yes">
                   <PARAM NAME="leftsum" VALUE="no">
                   <PARAM NAME="uppersum" VALUE="no">
                   <PARAM NAME="lowersum" VALUE="yes">
                   <PARAM NAME="generalsum" VALUE="no">
                   <PARAM NAME="showinfo" VALUE="yes">
             </APPLET>                          
 

The parameters allow the applet to be configured with an arbitrary function, minimum and maximum x values, number of points to partition by, and whether to compute the various kinds of sums.

We'll examine this technique in detail in the next section.

Components

Components offer a powerful means of designing for reuse. We define a component as an independent, reusable software entity which may be assembled with other components into applications with little or no programming. Component vendors need not know in advance how their components will be used. Instead, they can use programming conventions to ensure that their components can interoperate with others. Component software is a thriving industry; there are many software vendors producing components that are not applications in their own right but useful only in combination with other components. There are also extensive efforts to catalog existing components and catalyze development of new ones. An example of this is at Flashline.com.

In Java, components are called JavaBeans ("beans" for short). A bean is a class that adheres to some simple programming conventions and provides a description of the bean's properties and other information relevant to a builder environment, such as icons. The builder uses a process called introspection to determine the bean's properties and automatically create property editors to customize the bean. After customizing and wiring the beans, the final assembly is saved in a human-readable text file. An applet could be a bean, but since an applet implies deployment in a web browser, it may sometimes be more useful to implement most of the functionality of your mathlet as a bean and use an applet as a thin wrapper around the bean. For more information on JavaBeans, see the JavaBeans trail of the Java Tutorial.

Among the developers of JOMA mathlets in Volume. 1, Issue 1, Alan Cooper successfully converted GraphExplorer to a JavaBean.

In the ESCOT project we've adopted a component approach that we call "rapid assembly componentware" [DiGiano & Roschelle, 2000]. We use the JavaBeans component model as a foundation and use a builder environment to rapidly create component assemblies. Whereas standard JavaBeans builder environments such as the JavaBeans Development Kit wire components together using semi-automated programming, we've simplified this so that one need only specify the properties to connect in both components. Our vision is that you could create sophisticated activities by dropping components into a builder environment, customizing them, and wiring them, without doing any coding or debugging. Practically speaking, however, we've found that these environments require technical expertise to use.

A bean is distributed not as source code or class file, but as a jar file, which is similar to a zip file except that it contains one or more class files and a manifest describing the contents of the jar file. This distribution strategy allows you to distribute your bean in one convenient file while protecting your source code, because you can "obfuscate" the class files, effectively hiding them from prying eyes. Jar files are created with the jar tool provided in the Java SDK, or with similar facilities in IDEs.

We will go into more detail about how to create a bean in the next article.

Packages

Another Java tip that bears on reuse is to use packages. While it may seem convenient to keep everything in the default package (i.e. no package declaration at the top of the file), this becomes a problem if you start to reuse code which also defines classes inside the default package, with the same name. You can prevent name collisions by putting your classes in their own package. The convention is to name the package in reverse order of a domain name. For example, our domain name is escot.org, so our packages are named org.escot.*.

Documentation

There are some software engineering techniques that also make designing for reuse easier in Java. For example, documentation is an important means of communicating to other developers what your class does. Java provides a technique and a tool called javadoc, which allows you to generate nicely formatted documentation from source code that has been commented using some simple conventions. The basic convention is to precede classes, methods, and method variables that you want to publicly document with /** comment here */. For example,
 

   /**
       This is an example of a javadoc comment for a class.
   */
   public class MyBean extends Panel {
       /**
           Here  is documentation for the constructor.
       */
       Public MyBean() {
       }
   }

Simple, isn't it? Because the documentation is generated from the source code, it is easy to keep it in sync with the source code. The Java API documentation was produced this way, and if your documentation looks similar, it will be much easier to navigate. See the Javadoc Home Page for more information. (Note that the output of the Java 1.3 javadoc tool is better than the Java 1.1 javadoc tool. Even though you may be writing to Java 1.1, you may want to use the Java 1.3 javadoc tool). Explanatory documentation external to the API documentation is always helpful as well; see Alexander Bogomolny's JOMA article for an example of external documentation.

Testing

Another technique important for reuse is automated testing. How do you guarantee that your software works as advertised? Often with component software it is necessary to make modifications to components based on end user or developer feedback. Automated testing can ensure that the component doesn't break unexpectedly because of changes, and if you have a sufficient test suite, can make you confident that making changes to the source won't break anything. JUnit is a popular, free, and easy to use framework for automated testing in Java. Since it's automated, you don't need to configure tests or check the results of each test; JUnit will report if any tests failed and allow you to get information on the failures. Happily, JUnit was designed with the philosophy that it should be simple, otherwise programmers won't bother writing tests.

Your applet can read a parameter specified in the HTML simply by using the Applet.getParameter() method, which takes a String specifying the parameter name. It returns the value as a String if the parameter was specified, or null if not specified. Since you will want to handle the case in which the parameter is not specified by using a default value, you could add a convenience method to your applet class. It reads a parameter with the specified name and returns the value as a String, specifying a default value in case the parameter is not found:

 public String getParameter(String key, String def) {
     if (getParameter(key) != null)
         return getParameter(key);
     else
         return def;
 }

Here is an example of how to invoke this method to get the value of a parameter named "xlabel", providing a default value, and to pass the value to a setter method:

setXLabel(getParameter("xlabel", "X"));

The following method reads in a parameter as a float and specifies a default value in case the parameter is not found or there is a problem parsing the value as a float:
 

public float getFloatParameter(String key, float defaultValue) {
    try {
        if (getParameter(key) != null)
            return Float.valueOf(getParameter(key)).floatValue();
    }
    catch (NumberFormatException nfe) {
        nfe.printStackTrace();
        // fall through and return default value
    }
    return defaultValue;
}

Similar methods could be written to get parameters of different types.

Here is an example of how to invoke this method to get the value of a parameter named "xmin", providing a default float value:

setXMin(getFloatParameter("xmin", -10.0F));

The Applet API also provides the method getParameterInfo(), which you can override to provide information so that a web browser could present an interface to change the parameters. Currently, no web browsers use this information, but you may choose to implement this for completeness. For more information, see the section Giving Information about Parameters in the Writing Applets trail of the Java Tutorial.

We have examined three kinds of reuse: application reuse, designing for reuse, and code reuse, which give mathlet developers and teachers the ability to leverage prior work to create new mathlets. The JOMA mathlets represent the cream of the crop of online mathematical activities, but even they have room for improvement to support reuse. We presented an assortment of techniques for mathlet developers to improve reusability. In the next article we'll go into depth on beans and interoperability.

DiGiano, C. and J. Roschelle (2000). "Rapid-Assembly Componentware for Education," pp. 37-40 in Proceedings of the International Workshop on Advanced Learning Technologies at Palmerston North, New Zealand. IEEE Computer Society Press, Los Alamitos, CA.

Leach, Ronald (1997). Software Reuse, McGraw-Hill, New York.

Raymond, Eric (1999). The Cathedral & the Bazaar, O'Reilly & Associates, 1999.