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

[Miguel Colom]

> Section PORTABILITY: This section seems to say (although it does not
> really say) that IPOL programs will compile on standard environments
> of linux, mac and windows.  This is far from true.  For example, any
> C99 program will not be compiled by Visual C.

I think the idea is that code should follow standards (ANSI C, for
example),  and this ensures that it's independent from the platform.
Even if Visual C doesn't respect standards or doesn't recognise C99, the
solution is to use a compiler that does. For example, Netbeans [1].

> 2. I agree strongly to forbid white space at the end of lines and
> enforce correct indentation.  This is like asking english text to be
> free of typos (text with typos conveys the same message, but looks
> weird and not serious to many people: the same thing happens with
> incorrectly formatted code).

I'd recommed using a lint tool to clean the code.

> 3. If disallowing CR+LF terminations is too strong a requirement,
> mixed files (some lines ending in newline, some in CRLF) should be
> disallowed.

A lint tool would tell about these too.

> 4. 1000 lines per file is probably too few for people who prefer a
> literate programming style, where the whole main function is written
> in a single file with intertwined comments

I agree. Instead, I think it's better to talk about a maximum number of
lines in each function, instead of those in each file.

> Section LICENSE: Why is not the AGPL license included?  This licence
> is very relevant for IPOL, since it forces that all "remotely
> executable" copies of the software provide a means to get the source
> code.  With classical GPL and BSD licenses, somebody could run a
> mirror of IPOL with some modified algorithms and not publish their
> source code.  Authors who are worried by this problem could choose the
> AGPL.

I strongly agree with this. AGPL was designed to solve exactly that problem.

> Section SOURCE CODE DOCUMENTATION:
> 1. How do we link from the source code to the mathematical description
> 2. The requirement that all functions must have a comment rules out
> self-documenting code.  This looks ridiculous to me:
>
> // sum two vectors
> void sum_two_vectors(float *out, float *in1, float *in2, int n)
> {
> ...
> }
>
> In that case, I would say that the comment is distracting and thus,
> incorrect.

The key is that it allows for automatic documentation, for example, with
doxygen.

Best,
Miguel

[1] http://forums.netbeans.org/ptopic29318.html