[IPOL discuss] revision of the Software Guidelines - first draft

[eml]

Dear Nicolas,

I make some minor comments to the new draft of the software guidelines.



> * Clarify the use of external libraries packaged with the software
>   (foreign code).
>
>   This covers cases like the use of Eigen, or other libs, as
>   building-blocks for an IPOL code. Such libs must be C/C++,
>   standard and portable, and their usage should be isolated from
>   the author's code. I would like to add a condition on size, like
>   "no huge library for a tiny algorithm", but I couldn't find a
>   good expression.

The expression that you quote seems perfectly appropriate and clear to
me.  I would supplement it with an example: "To compute the
eigenvalues of a 2x2 matrix,  you SHOULD NOT use a linear algebra
library".



> * Recommend to replace tabs by spaces.
>
>   This avoids choosing if tabs are 2, 4, or 8 characters.

I do not agree with this addition (even if it's my favourite flamewar
subject).  This is a minor and irrelevant issue about which many
programmers have strong opinions.  We should not give this
recommendation, and much less for the stated reason (since it serves
as well to enforce tabs instead of spaces).  I guess that the reason
for this change was to provide a precise meaning for the 80-column
limit.  If this is the only reason, then the desired precise meaning
can be obtained by specifying how the number of columns is to be
computed (e.g., by counting the tab character using tabstops of size
8).


>From the document:

> Only C89 (ANSI C), C99, and C++98 (ISO C++)4 can currently be processed.

This sentence is confusing, and will be more confusing in the future.
Since ANSI ratifies ISO standards a few years later than they are
published, the expression "ANSI C" currently refers to C99, and not to
the outdated C89 language, which was commonly named ANSI C to contrast
it with the older K&R.  I propose to make an explicit list of the
accepted language standards, with links to the appropriate standard
document:

* C89: http://webstore.ansi.org/RecordDetail.aspx?sku=AS+3955-1991
* C99: http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf
* C++98: (could not find it)



> The source code may use the OpenMP 3.0 API for shared multiprocessing programming (parallel programming) but it must also compile and provide the same results (albeit slower) without OpenMP.

It is difficult to understand what does "must also compile" mean in
this case.  If a program uses openmp in a nontrivial way then it
includes the file "omp.h".  If you try to compile such a program in an
environment which does not support omp, the compilation will fail
because this file is missing.  Thus, to make it compile without omp
you must change the program, and the requirement of the guidelines is
impossible to fulfill.  I suggest to change "must also compile" to
"must compile with minimal changes", or to force that all omp-specific
code be hidden behind appropriate #ifdef macros.