Reviewers Guidelines for the Forth Scientific Library

 
       Here are some guidelines for reviewers of the Forth Scientific
       Library project, together with some information about how the 
       reviewing procedures are handled.  The reviewing of contributed
       code by volunteers is an important and valuable component of the
       FSL Project.

       It may also be helpful to look at the guidelines for contributors, 
       and browse through some of the current contents of the Library.


 The primary task of the reviewer is to ensure that:

 1). The code adheres to the coding guidelines.

 2). That the code can be properly run on an ANS compliant system.

 3). The test code gives correct results.


 For point one it is especially important that the environmental
 dependencies are completely stated.  It is very easy for the
 author to miss something here, since once he loads in his standard
 tools he might forget that some part of it, that is not in
 everyone else's toolbox, is being used.

 Also make sure that version numbers and dates are given, otherwise
 code maintainance will become a nightmare.

 Please verify that the code has a proper copyright/release statement.


 The ANS compliance part may take a little work on the reviewer's
 part if he isn't using a "pure" ANS system himself.  Some systems
 include tools for checking ANS standards compliance.  In any case
 it can be useful for reviewers to try using as many different
 Forth systems as they can, to help identify subtle dependencies.


 The proper running of the test code will also help in finding
 implicit environmental dependencies.  Presumably the code ran
 properly on the author's system, but it might behave differently
 on another system.  In some cases a reviewer may decide to do some
 additional testing, for example to check that "corner cases" get 
 handled correctly, or that there aren't limitations that should
 be documented.



 A secondary task is in reviewing the coding style, conventions,
 and usefulness of the comments.  This will require a bit of
 balance.  On the one hand, we want this code to reflect well
 on Forth and hope to see it used by programmers that traditionally
 use Fortran, so we want cleanly designed code.  On the other hand,
 it can be tempting to declare all code not written according to
 our own personal vision as poorly written code.  (Since both 
 contributors and reviewers are Forth users, they are used to being 
 able to have things done according to their own preferences, which
 are apt not to be identical.)  So please try to be careful here.
     


       The customary procedures for the reviewing of contributions 
       work as follows:

 1.  The contributor sends his submission to the project coordinator,
 currently Charles Montgomery <cgm@physics.utoledo.edu> by email.
 [hereinafter referred to in the first person]

 2.  The list of contributions available for review is published in 
 the status report on the Taygeta site, and may sometimes also be 
 posted to the sci.lang.forth newsgroup.  Anyone interested in reviewing
 a particular contribution can let me know by email.

 3.  I send a copy of the contributed code to the reviewer.  The
 reviewer and the contributor can then discuss the contribution by 
 email (or any other way they wish).  When there is a final version
 both are satisfied with, either one sends me a copy (preferably 
 with a copy also to the other, just to ensure there isn't any 
 version mix-up).

 4.  I assign an algorithm number to the contribution, and add it to
 the official Library collection at www.taygeta.com/fsl/scilib.html



     It should be noted that none of the guidelines for contributors
     or reviewers or the procedures are intended to be completely
     inflexible.  They work well and provide a useful consistency,
     but adjustments can always be made if a particular case calls for
     them.  (For example, if either the contributor or reviewer were
     not comfortable with how the review process was going, for any reason,
     it would be easy to simply revert to step 2 in the process above.  I
     don't know of that situation ever arising, but it could be handled
     without difficulty if it ever were to occur.)



This file is based on a version originally written by Skip Carter, augmented 
by C. G. Montgomery.               Latest revision 29 Nov 2004  cgm.
[ed. note by cgm:  In a hopelessly old-fashioned manner, the words "he","him","his"
are used in this document in their general sense, with no implication whatsoever 
of gender, which would be totally irrelevant anyhow.]