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

[Nicolas Limare]

Pascal, and everyone,

I answer quickly to most of the points because they are mainly errors
I did in choosing the words. On most items I agree with Pascal but I
did not express it correctly.

I also completely subscribe to his three preliminary general
comments. The intention is a guideline, and it has to address the needs
of the IPOL projects *and* the "feelings of the IPOL community". I
hope this document can converge to a soft consensus.

> The check list in Annex C is a very good idea.

I will move it to the beginning of the document, for readers too
frightened by the long text.

> # 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.

Bad wording... The "MUST" was about the zip/tgz archive format, and
the "single" was to avoid zip archives in multiple volumes. But
"multiple volume" zip archives are forbidden in the next sentence, so
I will remove "single" here, and add that an IPOL article MAY publish
many softwares or a demo MAY use many softwares, each distributed as a
compressed archive file.

> ## 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).

Bad wording... I want to say that the software name doesn't need to be
the name of the program, because if your compiled program is called
"denoise", you probably want something more explicit for the name of
the software. I will rewrite the end of the sentense more clearly.

I also anticipate the idea of unique software names in IPOL, but it is
too early, we don't have the tools and the use for it now.

> > 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 [...] I suggest reducing
> this rule to "MAY".

Can we agree on SHOULD? And ask the reviewers to be careful with heavy
hidden folders (.git, .svn), but flexible on light hidden files.

> > 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.

Yes, these utilities, and others, can be useful. I propose to replace
"needed to build" by "useful to build, use or study".

> ## 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?

The idea is: other standardized compiled programming languages are OK
for the IPOL reproducibility goals, but we don't have the expertise
and toolchain to handle them. If you want to use these languages,
contact us, we will try to find a solution. I will improve the text.

We also need to add a condition on the populatity of the language,
because we will need to have some reviewers. Haskell is nice, COBOL
and ADA are standard, but few image processing researchers are
proficient in these languages.

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

No, of course. C and C++ is the standard example example. I will
replace by "in one or more compiled programming languages".

> ## 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.

Agreed. And libjpeg is a dependency of libtiff, it is needed.

> ## 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."

Right, here again this was my idea, thanks for expressing it
clearly. I will keep your sentence.

> ## 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

Yes. I did some excessive copy-paste. It can be included in the future
"Coding Guidelines" (only a concept for the moment). By the way, these
"coding guidelines", if written, would only be PROPOSED for new
authors with few or no experience in writing a code read by
others. It is NOT to enforce an unified coding style.

> > 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.

Here again I went too far, excessive copy-paste too. What about asking
(SHOULD) that all files in the software use the same terminators? This
may requires some additional explanations for authors who don't know
what it is.

> > 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.

Here again, this belongs to the future coding guidelines, not here.

-- 
Nicolas LIMARE - CMLA - ENS Cachan    http://www.cmla.ens-cachan.fr/~limare/
IPOL - image processing on line                          http://www.ipol.im/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
URL: <http://tools.ipol.im/mailman/archive/discuss/attachments/20111106/294a5c80/attachment.pgp>