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

[rafael grompone von gioi]

Salut Nicolas,

Ton document me semble superbe.
En fait, je n'avais pas eu le temps de le lire avant,
j'espère ne pas dire de choses que on était déjà
discutes.

J'ai 2 petites suggestions:

1) Section 2.8

Plusieurs fois dans le document c'est marque "but not limited to"
et je pense que c'est une bonne chose pour donner des exemples
mais laisser claire que sont que des exemples. L'importance est,
je crois, que donner une liste exhaustive de choses a ne pas faire
est impossible.

Par contre le cas de la section 2.8 me semble différente.
Pour quoi ne pas donner la liste exhaustive des formats acceptes?
Ce n'est pas semblable au cas des librairies? Si ce n'est pas la,
ou on doit aller pour savoir quel formats on est autorisé a
utiliser?


2) Dans le paragraphe:

The source code of an IPOL Program MUST be very readable, commented
precisely and exhaustively. Comments MUST be abundant and SHOULD
attain the 1/8 comment/instruction ratio but the quality of these
comments is more important than the quantity.

Je pense que la deuxième ligne pourrais être plus claire comme ça:

  Comments MUST be abundant and SHOULD attain the
  1/8 comment/instruction ratio, but the quality of these
  comments is more important than the quantity.

avec une virgule avant "but", ou encore mieux comme ça:

  Comments MUST be abundant and SHOULD attain the
  1/8 comment/instruction ratio. But the quality of these
  comments is more important than the quantity.

Je dis ça car il me semble que il y en a 2 idées différentes:
le ratio 1/8, ET souligner la qualité des commentaires.

rafa



On Mon, Nov 21, 2011 at 2:40 PM, Nicolas Limare
<nicolas.limare at cmla.ens-cachan.fr> wrote:
> Dear all,
>
> The second draft of the IPOL Software Guidelines is available online:
>  http://tools.ipol.im/wiki/author/code/software_guidelines/
>
> I tried to integrate all the remarks received about the first
> draft. A summary of the changes is included after in this message.
>
> Please read it, and let me know if something needs to be explained or
> changed, or if I forgot your previous remarks. If everything looks
> fine, please also send me a short mail just to say it's OK (no need to
> use the list for that); this way I'll know some people read it. If no
> substantial modifications is needed, I will propose a first official
> version next week. If some changes are needed, it will be a 3rd draft.
>
> 8<----------8<----------8<----------8<----------8<----------8<----------
>
> So, what's new in the 2nd draft? Remember: MUST is a hard condition,
> non-negotiable; SHOULD is a soft recommendation, negotiable if the
> authors, reviewers and editors agree.
>
> * no mention of automated processing in the preamble, this will be for
>  a further extention, later
> * the checklist is at the beginning of the document
> * links to an example program (axpb) and a check tool are provided; for
>  the final version of the guidelines, this will be installed on
>  tools.ipol.im and a web interface will be proposed to check a code;
>  the check tool is minimal now, will be explanded later
> * using multiple programs in an article or a demo is explicitely
>  allowed
> * the guidelines are numbered for easy references
> * no mention of lowercase/uppercase for file names
> * hidden files and files not used to build, use or study the
>  algorithm SHOULD NOT be included
> * other languages (Fortran90) are mentioned
> * libjpeg and zlib allowed, mention of the float and double variants
>  of fftw
> * possibility to provide compilation options specific to a compiler
>  but not in the default build procedure
> * clarification of the file formats (at least one standard format)
> * added stack info
> * "source code quality" replaced by "readability"
> * added a list of tools for code cleanup
> * the code MUST be consistently spaced and indented, SHOULD be less
>  than 80 chars, SHOULD have no white spaces at the end, SHOULD be
>  less than 1000 lines and all use the same line terminations
> * no mention of future "coding guidelines", they will be announced
>  when (if?) released
> * added LGPL/AGPL licenses
> * clarified the 3 license cases: no patent, external patent and patent
>  by the code authors
> * authors SHOULD provide an example of input file to test the IPOL
>  program, and the result to expect when this input file is processed
>  by the program
>
> And I fixed various typos, and tried to make some sentences more clear.
>
> --
> Nicolas LIMARE - CMLA - ENS Cachan    http://www.cmla.ens-cachan.fr/~limare/
> IPOL - image processing on line                          http://www.ipol.im/
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.10 (GNU/Linux)
>
> iEYEARECAAYFAk7KVMYACgkQvviFAPpCP08B4ACeLnUFVqvwTpf4q9bSSjPRzPbG
> Eq4AnAiOc9HQ7bPMFexlWOhuN9p86/yU
> =1gbM
> -----END PGP SIGNATURE-----
>
> _______________________________________________
> discuss mailing list
> discuss at list.ipol.im
> http://tools.ipol.im/mailman/listinfo/discuss
>