faq 29229089

How to provide coding examples?

by Kai Nagel on 2015-06-03 10:19:53

---

Coding examples that are pasted into documentation have a tendency to be out of date.  What are the alternatives?

---

Comments: 1

---

Re: How to provide coding examples?

by Kai Nagel on 2015-06-03 10:53:25

Here are some rules that we try to follow when providing coding examples.  Please let us know if you have additional ideas.

Avoid pasting exact code examples into documentation.  

Instead, do something like: "The code looks something like this:

controler.addOverridingModule( new AbstractModule(){
    ... install() {
       this.bind( TravelTime.class ).toInstance( new FreeSpeedTravelTime() );
    }
 });

 

For a working example, see matsim.org/javadoc → main distribution → RunCustomTravelTimeExample class."

Always provide this working example (see next point).

Provide a working example inside the matsim repository.

In the main distribution, the normal place for this is in the tutorial.programming.* package.

The class name for this shall start with Run...  With this convention, one can find such classes easily in the javadoc.

The reason for having the code examples in the repository is that, with this, they are included in our refactorings, and will thus reflect the changes in the matsim core.

Use robust pointers to the working example.

Do not use something like http://ci.matsim.org:8080/job/MATSim_M2/javadoc/tutorial/programming/example20customTravelTime/RunCustomTravelTimeExample.html since this has a tendency to become obsolete.  Instead, use "See http://matsim.org/javadoc → ... → RunXxx... class."  Advantages of this approach, besides providing a more stable URL, include:

• The approach will include backwards-compatible coding examples with each release (see http://matsim.org/javadoc to understand this).
• As long as the class name remains there, it can be moved from one package to another.  That is, we decided to rather keep the class names stable, but possibly re-organize packages/package names.

Point to the working example from other places in the code.

For example, the TravelTime class contains a pointer to the code example:

/**
  * A simple interface to retrieve the travel time on links.
  * <br/>
  * For an example of how to replace this, see {@link RunCustomTravelTimeExample }.
  *
  * @author mrieser
  */

Nice things about this include:

• This will provide a clickable link in the javadoc.
• The link is adapted over refactoring both if the class name and/or the package name change (the package name is included as import statement).