[IPOL discuss] comments needed : [draft] IPOL Software Guidelines v.1

Sun Nov 6 08:06:31 CET 2011

Dear all,

Thanks to Nicolas for version 1 of the IPOL Software Guidelines
document.  It is very carefully and clearly written, and when it is
official, it will clarify the goals for code reviewers.

I have a few general comments:

First, I warn that as all us on this list are firmly invested in the
development IPOL software, this discussion is likely to get strongly
opinionated and will require compromise.  Let me be point out that
proposed rules are not and should not be considered as criticisms
directed at anyone in particular, but as rules intended to promote
quality and consistency.

Second, I believe code requirements should be forgiving where possible
to authors who are less programming inclined since mathematicians are
a sizable portion of IPOL's intended audience.  Researchers in other
imaging-related disciplines may also vary in which software practices
they are capable.  So I hope that most of the points here can be of
the "MAY" or "SHOULD" enforcement category.

Finally, I also warn that when a committee discusses a lists of rules,
there is a tendency to produce a long and overly-detailed list, which
is overwhelming to anyone who reads it later.  (Imagine how long this
thread will be when we are done!)  I hope that the rules here,
particularly the "MUST" rules, can be distilled to a minimal number of
essential points.  The check list in Annex C is a very good idea.

Now I list my suggestions on the rules in the order in which they are
in the guide.

# Archive
> An IPOL software MUST be packaged as a single compressed archive file.

I suggest weakening this to a "RECOMMENDED" requirement to make an
exception for benchmarks.  In a benchmark comparison of multiple IPOL
articles, the benchmark software must run the software associated with
each article.  The Python demo for the benchmark only needs to collect
all the sources of the articles in its "build" function.  I used this
approach in my prototype demosaicking benchmark:
http://dev.ipol.im/~getreuer/ipol_demo/g_demosaicking_bench/

## Archive File Name
> name MUST be at least two characters long and start with a letter;
> it MUST indicate the name of the software, which MAY not be the
> name of the executable program provided by this software

What is the reason for requiring "name" to be distinct from the name
of the executable program?  For an archive that only builds one
program, the name of the program seems to be a natural choice (pardon
my naivety).

# Content
## Hidden Files
> An IPOL software MUST NOT include hidden files or artifacts of
> the tools used by the authors

While I agree that this is good practice, it is non-essential from the
point of view of being able to compile and run the code.  Furthermore,
it may well be difficult for some authors, depending on their file
manager or archiving tool, to view and delete these hidden items.  For
example, WinZip (under default settings) will hide empty directories
when displaying the contents of an archive [1].  I suggest reducing
this rule to "MAY".

## Source Code
> If the authors want to distribute binary versions, this MUST be done
> out of the IPOL software archive.

(Language) Change "out of" to "outside of".

> The software SHOULD NOT be distributed with source code files not
> needed to build the implementation of the algorithm published in IPOL.

Further detail is needed here to say whether utilities used by the
demo (e.g., for computing difference images) are allowed in the IPOL
software archive.  Arguably these utilities should actually be
packaged separately, as utilities tend to be reused across multiple
demos.

## Programming Language
> The source code of an IPOL software MUST be written in a compiled
> programming language and follow a published standard syntax;
> currently accepted standards are C89 (ANSI C), C99, and
> C++98 (ISO C++).

This rule needs clarification: is the intention to say that only C and
C++ are accepted by IPOL, or are other standardized compiled languages
(e.g. Fortran 77, 90, 95 and Haskell 98) allowed as well?

Additionally, the rule says "in a compiled programming language."
Should a source code be prohibited for using more than one language?

## Dependencies
To be clear, zlib (dependency of libpng) and the "fftwf"
single-precision variant of the FFTW library should be listed here as
well.  I suggest to allow also the libjpeg library.

## Usage and Input/Output
> It MUST read and write data files in standard and documented
> formats, such as (but not limited to) PNG or TIFF image files, EPS
> or SVG vector files, PLY or VRML meshes.

In my opinion, the critical requirement is that the IPOL software
*can* accept the input data and generate the *final* output data in
standard and documented formats.  I suggest weakening to "SHOULD" or
instead rewording as

"It MUST be possible to read the input data and write the final output
data in at least one standard and documented format, such as (but not
limited to) PNG or TIFF image files, EPS or SVG vector files, PLY or
VRML meshes."

By rewording it this way, the use of nonstandard file formats for
temporary/intermediate data is implicitly allowed, e.g., to
communicate intermediate computations between programs.  Also the
software is allowed to accept input data or generate final results in
nonstandard formats, in case the author thinks this is useful,
provided that the software can also handle input and output in
standard formats.

If nonstandard formats are used, certainly explanation of this would
be expected, but this is a matter of code documentation.

## Source Code Quality

I suggest removing the following rules regarding formatting.

> there MUST NOT be any whitespace at the end of the lines

This is good practice but non-essential, and moreover, not necessarily
easy for authors to ensure depending on their skill level and editing
software.  I have tried a few automatic trailing whitespace removal
methods, but they also remove the indentation level of blank lines,
which is makes further editing of the code uncomfortable.

> The DOS CR+LF line terminator MUST NOT be used.

This is non-essential and unfair to DOS/Windows users, who would have
particular trouble to satisfy this.  Any decent modern text program
can understand both LF and CR+LF line terminators.  Furthermore, the
popular Microsoft notepad program *only* handles CR+LF (yes, notepad
is neither decent nor modern), so it is reasonable to encode at least
the readme.txt with CR+LF.

> they MUST end with a correcly terminated line and there
> SHOULD NOT be empty lines at the end of a file.

I have no idea why this would matter.  It may be a legacy convention,
like Fortran code written entirely in uppercase.

## Source Code Documentation
> the quality of these comments is more important than the quality.

(Language) Change second occurrence of "quality" to "quantity".

[1] http://britishinside.com/archive/2007/06/18/Zip-files-and-hidden-folders.aspx

On Sat, Nov 5, 2011 at 21:31, Nicolas Limare
<nicolas.limare at cmla.ens-cachan.fr> wrote:
> Hi,
>
> Because of recent misunderstandings on the meaning of the IPOL source
> code requirements, and other things I wanted to correct, I wrote
> a first draft of the IPOL Software Guidelines, version 1.
>
> -> http://tools.ipol.im/wiki/author/code/software_guidelines/
>
> This document incorporates, extends and will replace the current
> Implementation Manual and Copyright and Patent Policy.
> -> http://www.ipol.im/meta/submission/manual/#implementation
> -> http://tools.ipol.im/wiki/author/code/copyright_and_patents/
>
> It should describe all the requirements an IPOL software must fullfill
> to be acceptable for IPOL.
>
> Now I need your comments, to correct and improve this draft and obtain
> an official version. Please post your comments on this list, I will
> prepare a second draft after 2 weeks. I am interested in any comment,
> but particularly in
> * imprecisions and ambiguity
> * disagreements about a requirement/recommandation
> * ununderstandable requirement/recommendation
> * requirements hard to attain for some of the authors or algorithms
> * proofreading by native English speakers
>
> PS: read and check the guidelines, because once it is they are adopted
> you will have to follow them!
>
> --
> Nicolas LIMARE - CMLA - ENS Cachan    http://www.cmla.ens-cachan.fr/~limare/
> IPOL - image processing on line                          http://www.ipol.im/
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.10 (GNU/Linux)
>
> iEYEARECAAYFAk6141wACgkQvviFAPpCP09bUACdEqRcYpp0zS4EaDFFzMiijlX6
> 9CMAn3hpkMtqhtoS6PyeLr7e4RJhpt4a
> =+hOt
> -----END PGP SIGNATURE-----
>
> _______________________________________________
> discuss mailing list
> discuss at list.ipol.im
> http://tools.ipol.im/mailman/listinfo/discuss
>