[IPOL discuss] IPOL Software Guidelines, 2nd draft (and last one?)

[Pascal Getreuer]

Dear Nicolas,

This document is excellent!  It is clear, realistic, detailed, and yet
concisely stated.

I have one concern:

> Authors MUST avoid unnecessary programming tricks that
> shorten the code but make its comprehension difficult to
> nonprofessional programmers. Clarity is more important
> than virtuosity.

The reviewers will have to decide what is "unnecessary" or "difficult
to nonprofessionals," which is vague and controversial.  At an
extreme, anything outside of a Turing-complete subset of C is
"unnecessary" (ergo, C++ is unnecessary?).   Also, people have
different ideas about the dividing point between "professional" and
"nonprofessional."

I suggest something more specific as a replacement:

"Authors MUST ensure that the code is understandable, to
the satisfaction of the editor and reviews, so that consistency
between the code and article can be verified.

Authors SHOULD apply simpler implementations when they
are available, follow the conventions of the programming
language, and use comments to explain complicated points
in the program.  Clarity is more important than virtuosity."

Personally, I would be OK with reviewing a very weirdly-coded program,
provided there are ample comments explaining how and what the program
is doing.  The key thing is being able to check consistency.


Minor wording thing (in 2.5 Portability):
   "A special attention will be given"
should be
  "Special attention will be given"


Pascal