23. README files again!

Part of CS:2820 Object Oriented Software Development Notes, Fall 2020
by Douglas W. Jones
THE UNIVERSITY OF IOWA Department of Computer Science

 

Introduction

Over the past lectures, we've taken a single source file and broken it into multiple source files, then used Javadoc to create documentation. The result has one key downside, the huge number of files that choke the directory for the project. Here's what you get if you do an ls command on the directory for our road network simulation:

[dwjones@fastx01 ~/project]$ ls
 allclasses-frame.html                'RoadNetwork$1MyEvent.class'
 allclasses-noframe.html              'RoadNetwork$2MyEvent.class'
 constant-values.html                  RoadNetwork.AAA
 deprecated-list.html                  RoadNetwork.bak
 Error.class                           RoadNetwork.class
 Error.java                            RoadNetwork.html
 help-doc.html                         RoadNetwork.java
 index-all.html                        RoadNetwork.shar
 index.html                            script.js
'Intersection$ConstructorFail.class'   serialized-form.html
 Intersection.class                   'Simulator$Event.class'
 Intersection.ConstructorFail.html     Simulator.class
 Intersection.html                     Simulator.Event.html
 Intersection.java                     Simulator.html
 MyRandom.class                        Simulator.java
 MyRandom.html                         Sink.class
 MyRandom.java                         Sink.html
'MyScanner$ErrorMessage.class'         Sink.java
 MyScanner.class                      'Source$1MyEvent.class'
 MyScanner.html                       'Source$2MyEvent.class'
 MyScanner.java                        Source.class
'NoStop$1MyEvent.class'                Source.html
'NoStop$2MyEvent.class'                Source.java
 NoStop.class                         'StopLight$1MyEvent.class'
 NoStop.html                          'StopLight$2MyEvent.class'
 NoStop.java                          'StopLight$3MyEvent.class'
 overview-tree.html                   'StopLight$4MyEvent.class'
 package-frame.html                   'StopLight$5MyEvent.class'
 package-list                          StopLight.class
 package-summary.html                  StopLight.html
 package-tree.html                     StopLight.java
 pathtest                              stylesheet.css
 README                                test1
'Road$1MyEvent.class'                  test2
'Road$ConstructorFail.class'           test3
 Road.class                            test4
 Road.ConstructorFail.html             testfile
 RoadFiles                             tests
 Road.html                             testscript
 Road.java
[dwjones@fastx01 ~/project]$ 

If you use a GUI to look at the directory (as a "folder"), the clutter is no better. We can break this hodgepodge of files down a bit by using selective ls commands. Here is the list of just the java source files:

[dwjones@fastx01 ~/project]$ ls *.java
Error.java         MyScanner.java  RoadNetwork.java  Source.java
Intersection.java  NoStop.java     Simulator.java    StopLight.java
MyRandom.java      Road.java       Sink.java
[dwjones@fastx01 ~/project]$ 

Here is the list of just the files created as output from the Java compiler:

[dwjones@fastx01 ~/project]$ ls *.class
 Error.class                           RoadNetwork.class
'Intersection$ConstructorFail.class'  'Simulator$Event.class'
 Intersection.class                    Simulator.class
 MyRandom.class                        Sink.class
'MyScanner$ErrorMessage.class'        'Source$1MyEvent.class'
 MyScanner.class                      'Source$2MyEvent.class'
'NoStop$1MyEvent.class'                Source.class
'NoStop$2MyEvent.class'               'StopLight$1MyEvent.class'
 NoStop.class                         'StopLight$2MyEvent.class'
'Road$1MyEvent.class'                 'StopLight$3MyEvent.class'
'Road$ConstructorFail.class'          'StopLight$4MyEvent.class'
 Road.class                           'StopLight$5MyEvent.class'
'RoadNetwork$1MyEvent.class'           StopLight.class
'RoadNetwork$2MyEvent.class'
[dwjones@fastx01 ~/project]$ 

Here is the list of just the HTML files created by Javadoc:

[dwjones@fastx01 ~/project]$ ls *.html
allclasses-frame.html              package-frame.html
allclasses-noframe.html            package-summary.html
constant-values.html               package-tree.html
deprecated-list.html               Road.ConstructorFail.html
help-doc.html                      Road.html
index-all.html                     RoadNetwork.html
index.html                         serialized-form.html
Intersection.ConstructorFail.html  Simulator.Event.html
Intersection.html                  Simulator.html
MyRandom.html                      Sink.html
MyScanner.html                     Source.html
NoStop.html                        StopLight.html
overview-tree.html
[dwjones@fastx01 ~/project]$ 

Hidden in this mess are some files that try to help deal with this clutter, but what would be really nice is if we had some automatic help.

We did provide some navigation tools for this mess. One of them was the file RoadFiles, built following the rules for the Java compiler's @files compiler option.

Error.java
MyScanner.java
MyRandom.java
Simulator.java

Road.java
Intersection.java
  NoStop.java
  StopLight.java
  Sink.java
  Source.java

RoadNetwork.java

This is the same list of files we got from ls *.java but it has been sorted and whitespace has been added to document some of the relationships between files. If the Java compiler had allowed us to add comments, we could have done more, but just by sorting and adding whitespace, we've showed the layering of the application into support classes, simulation model and main class, and the indenting shows the interesectioin subclasses.

README files

Any time a large project reaches the point where there are too many files and no roadmap, we need to do something. In the UNIX world, the first solution to emerge was the README file. By convention, this name is always given in upper-case to make it stand out.

We've had a rudimentary README file for a while:

Road Network Simulator
Version: Nov 11, 2020 -- new simulation framework based on the Nov 3 version
Author: Douglas Jones

This distribution contains
-- README -- this file
-- RoadFiles -- the list of all Java source files
-- testfile -- a road network description to test the simulator

To build the simulator use the shell command: javac @RoadFiles
To generate HTML documentation, run the shell command: javadoc @RoadFiles

To test the simulator use the shell command: java RoadNetwork testfile

Other input files can be substituted for testfile.
    BUG:  document the input file format somewhere
Unfortunately, there is no single standard for the structure or contents of a README file, but there are a growing number of best-practices documents surrounding such files:

Red Hat's tutorial suggests the following sections

Some software distributions split these apart, so you might have a file called COPYRIGHT or LICENSE referenced from the main README file, and a file called AUTHORS constructed similarly.

Just to add to the confusion, there are several markdown languages that people use for README files. A markdown language is a grossly simplified markup language, designed to be trivial to edit using a plain-text editor such as vi or emacs. One of the common markdown languages commonly used on GitHub and with the .md file extension can be summarized by this brief bit of text:

# Title

Text between titles to
be set as a paragraph

Blank lines separate paragraphs

## Subtitle

* Bulleted list
* Another list element

### Sub-Subtitle

A paragraph of text introducing
a block of pre-formatted text

```
quoted source code
or shell commands
```

Just to keep people confused, a competing common markdown format uses this notation:

HEADING
=======

a paragraph of
text

Sub-heading
-----------

If you need _italic_ or **bold** or `monospace`
they are available

- Bulleted lists work
- And you can include [link text](http://url.of.link)

> block quotes marked
> like this bit of text

All of these markdown languages are intended to be easy to read in a plain text file without needing a manual to explain the markdown language. Each of these markdown languages has evolved to the point that they threaten to be as complex as HTML and violate their original intent. The general advice is to avoid this complexity. Keep things simple!

Many software tools now recognize the file extension .md, and if you try to use a markdown language for your README file, you may as well name it README.md and see how your desktop software responds when you click on it. Many of the common markdown file rendering programs try to accept any or all of the notations mentioned above.

So, as an exercise, let's try to write a better README for the road network simulator:

# Road Network Simulator

A discrte-event simulator for a road network, built in Java.  The
network consists of any number of intersections connected by roads.
Intersections may be guarded by stop lights or uncontrolled.  A
special intersection type injects vehicles into the model and
another consumes vehicles.  Roads and intersection have each have
the time it take a vehicle to traverse them.

This is really a feasibility demonstration, because the only output
it produces is a trace of activity.  Furthermore, vehicles have no
identity and no agenda but just bounce around the road network at
random.  There is no congestion penalty for roads.

## Install

This file contains a file called `RoadFiles` listing all the Java
source files.  Each source file contains one top-level class.
RoadFiles is divided into 3 sections:

* Utility classes including the simulation framework.
* The simulation model, roads, intersections and types of intersection.
* The main program to read the model and run the simulation.

### Prerequisites

The code is in Java 8, it uses some lambda expressions.

The following instructions assume use of some variant of the Unix
shell, as is commonly used on Linux and MacOS for command line input.

### Instruction

To compile the entire project, use this shell command:

```
	javac @RoadFiles
```

To build the HTML documentation for the internals of the code, use
this shell command:

```
	javadoc @RoadFiles
```

### Cleanup

The above steps created a large number of `.class` files containing
parts of the compiler output, and a large number of `.html` files
containing documentation, plus `package-list` and some `.css` and
`.js` files.  These clutter up the directory and, since all are
automatically generated, you can delete them with the following shell
command when they get in the way:

```
	rm -f *.class *.html package-list *.css *.js
```

## Usage

The distribution contains a file called `testfile` that describes a
trivial little road network.  After installing the simulator, you
can test and demonstrate it shell commands such as the following:

```
	java RoadNetwork testfile
	java RoadNetwork testfile 10.0
```

You may substitute your own road network description for `testfile`
and as the second example above demonstrates, you may specify a time
limit for the simulation shorter than the limit given in the test
file.  If none is given, the simulation will run forever.

BUG Unfortunately, we not yet written a decent description of the test
file format, so you'll have to infer that from the example.  Mea culpa!

## Contributing

Report bugs to the first author, although this project is not currently
under active development.

## Authors

- Douglas Jones, Department of Computer Science, University of Iowa

## License

Free software, the author makes no claim on it and doesn't want to be
bothered by people asking to use it.  Just take it, it's yours!

## Warranty

You get what you paid for.  If this does anything for you, great, but
don't bother me if it doesn't work.

## Version History

2020-11-12 -- new anti-lambda expression simulation framework

## Acknowledgements

Thanks to all the students who've suffered through the lectures during
which this simulation program was used as a running example.

Note that the Lisencing section above, with a home-brew lisence notice, is not a good idea. Writing a good software lisence takes work and some understanding of copyright law. If you intend the give away the software, you might considere consulting the Gnu General Public License, or GPL (see the Wikipedia article), or alternatiely, one of the Creative Commons licenses (see the Wikipedia article).These licenses have been gone over by good lawyers and crafted with far more care than you are likely to be able to devote to this subject.

Note that under current US law, everything you write is inherently subject to copyright, so if you do not explicitly give your rights away, they are yours, except if someone paid you to do the work. In that case, your employer owns the work. This us usually documented in an employment contract where you explicitly convey copyright for all work done on your employer's time to your employer.

A common result of the automatic copyright you own to everything you do is that the work becomes an orphan work. That is, with no copyright notice and no way to trace the author, others who find the work can make no use of it. A huge fraction of all software that has been written is now orphaned, with no legal way to make any use of it because the owner of the copyright cannot be traced.

Also note that the waranty disclaimer above is problematic. Because the software is given away free, I can release it with a warning and take no responsibility, but the moment I sell something, it falls under a common law warranty: The warranty of implied merchantability, fitness for purpose, and workmanlike quality (see Wikipedia).

If you sell something as simple as a shovel, even though you never mentioned any warranty, the mere act of selling the shovel and describing it as a shovel implies a warranty that it conforms to the usual expectations of what shovels do. Fitness for purpose indicates, in the case of a shovel, that it will actually dig, and workmanlike quality implies that the shovel was built to the usual standards of shovel making.

It is legal to sell something with a warranty disclaimer, for example, when you sell a used shovel "as is." At this point, the buyer assumes all liability for that shovel. Products sold "as is" usually come with a steep discount.

In the world of software, it is very common to sell with a strict disclaimer of all implied liabilities. Typically, these were printed on the shrink wrap covering the floppy disks that came from companies like Apple and Microsoft, and a typical term in the disclaimer said that, by breaking the shrink wrap, the buyer agrees to the terms of the disclaimer. These were called shrink-wrap lisences. Nowdays the act of clicking on the install button on a software distribution sometimes includes an agreement to similar disclaimers, and these click-through disclaimers are sometimes still called shrink-wrap license agreements.

The legality of such disclaimers is open to debate. I suspect that many programmers, in the future, will have to deal with offering real warranty terms on their code.