23. README files again!
Part of
CS:2820 Object Oriented Software Development Notes, Fall 2020
|
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.
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
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.