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

[Nicolas Limare]

Hi,

I answer to Enric and Miguel in the same mail, to limit the traffic on
the list.

When a comment on this draft seems common sense and I don't expect
anyone to disagree, I update a temporary version. I already followed
Jose Luis remarks, and rewrote the license choices for patented
algorithms. The temporary versions are listed at the end of the web
page, for your information.
-> http://tools.ipol.im/wiki/author/code/software_guidelines/

> Section PORTABILITY:  How realistic is it to exclude POSIX?  I see
> that windows is certified posix compliant (as opposed to linux).   I
> understand that this compliance can be enabled by downloading a free
> update from microsoft webpage:
>  For anyone with windows experience: is that true?  Can I really use
> posix calls on windows?

No. This only provides some POSIX _network services_ for Windows, for
integration in a network of posix machines. If I remember correctly,
it is things like NFS, telnet. This does not magically make all POSIX
calls available. That's why Cygwin exists, to provide a full POSIX
environment in Windows. With Cygwin, you can use POSIX system calls
and they will be handled by the cygwin dll.

> If that is the case, then all the world is effectively POSIX, and we
> can safely allow its useful capabilities in IPOL.

Unfortunately, a large portion of the desktop world is not POSIX but
Win32. A large portion of the IPOL audience is Win32. A large portion
of the research labs are Win32.

> Section COMPILATION:  This section seems POSIX-specific (because of
> the compiler options).  Does it clash with the previous exclusion of
> posix?

The POSIX compiler options are the only example of somehow portable
cross-compiler options. If I look at the MSVC documentation[1], I see
that the -c, -D, -E, -I, -L and -O options are also recognized by the
Microsoft compiler, with the same meaning (but with the Windows /x
syntax instead of the UNIX -x). So the only POSIX-specific options are
-g, -l, -o, -s. I remove -g and -s from the list, because debug
and stripping is not crucial for the default build. I don't see how to
avoid -o and -l.

[1]http://msdn.microsoft.com/en-us/library/fwkeyyhe.aspx

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

These guidelines are a compromise, because we need standard-compliance
and portability, and this portability MUST include Windows, and
Windows is not standard-compliant... So the guidelines ask for a
little of both, ie to be standard and to be usable in Windows without
too much effort. Requiring a Windows user to install a POSIX
compatibility layer like Cygwin (or a Linux user to use a Win32
compatibility layer like Wine) is currently considered too much
effort. Using another compiler, as pointed by Miguel, is OK. You may
need some appropriate tools to compile and run an IPOL program on your
system, but you will not need another operating system.

> Section COMPUTING RESOURCES: Please, say how much stack space will be
> available to the algorithm (so that programs can enable protection for
> recursive functions and variable-length arrays).

On the demo, `ulimit -s` tells me the (default) stack size is 8MiB. I
don't know it this default setting is often updated in Debian, but it
should not decrease over time. Info added.

> Section SOURCE CODE QUALITY:

I renamed this section "readability", because it should not be about
performance or elegant design.

> 1. Why 79 and not 80 characters?

Because I read somewhere that "some editors" have problems (ie insert
line continuation signs) if the line length is >= 80. I don't mind
changing this rule to 80 characters.

> 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

I would rather say it is more like an english text with irregular
spaces between words, paragraphs, ... I agree with your remark, except
that spaces at the end of line are only visually disturbing in the vi
editor.

Correct indentation (in any consistent style) is already enforced by a
MUST. For the spaces at the end of lines, maybe we can make it a
SHOULD, so this can be negociated between authors and reviewers.

And I follow Miguel's suggestion to provide a list of code
beautifiers. I listed "indent", "astyle", "uncrustify" and
"UniversalIndentGUI", but I only really used the first one. Are you
people aware of other tools for Windows or Mac OSX?

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

Already done in an update of the guidelines, after Pascal remarks.

> 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

It is already a SHOULD, so the authors can explain why more than 1000
lines makes sense for their code. If this is still a problem, which
higher "soft limit" would you suggest? 1500? 2000?

The idea was that long files contain too much things for one's working
memory and are hard to navigate. I understand Miguel's suggestion to
put a limit on the length of a function, but this is more "design
quality" than readability, and I think it will be hard to agree on a
limit suitable to all levels.

A limit on function length, and limits on the number of arguments, the
nuimber of branches, ... can be added in the future coding guidelines,
the style and design recommendations we may write later.

> Section LICENSE: Why is not the AGPL license included?

Bad wording. For me "GPL family" means GPL, LGPL, AGPL. Draft updated
to explicitly mention GPL, LGPL and AGPL.

> Section SOURCE CODE DOCUMENTATION:
> 1. How do we link from the source code to the mathematical
> description

With text in the comments, not real links. I replace this text by "The
correspondence between each part of the implementation and the respective
part of the mathematical description of the algorithm MUST be
explained in the comments."

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

This is an extreme example. On the other side, if we add "except for
trivial function", there will be arguments about what is or is not
trivial. The ridiculous "// sum two vectors" is the price we have to
pay to be sure we have a documentation of every non-trivial
function. And as Miguel said it is a way to push for Doxygen without
making it mandatory.

> There should be a direct link to the axpb.tar.gz template program (or
> to a similar template).

OK I will add a trivial example. Or one of you can write this example,
maybe from the axpb.tar.gz already available. Independant
implementations are good when we write a specification, and these
guidelines are a sort of spec.

PS: thanks to everyone for your constructive comments

-- 
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/20111109/c8ca799e/attachment.pgp>