On Mon, Nov 22, 2010 at 7:54 AM, Roberto Bagnara <bagnara(a)cs.unipr.it> wrote:
We have just published a new, improved and extended version of the article "Coding Guidelines for Prolog":
http://arxiv.org/abs/0911.2899Constructive comments are welcome.
Dear Roberto,
as with many coding guidelines, it is a matter of taste; nevertheless I agree with most of them (and I bet many Ciao users and developers too). Good job for putting all of them together in a single and easy to read text!
Here are some detailed (and personal) comments that I hope you and the rest of co-authors would find useful.
Section 2.2:
Ciao currently uses 8 space indentation (the emacs mode). I personally also like 4 spaces, and if everyone else agree I believe we can switch to 4 spaces.
Section 2.16:
Most of the inconsistencies that I found in Prolog code is for indentation of if-then-else and disjunctions.
I personally use:
% note the single space ( disjunct_1 ; disjunct_2 ; disjunct_3 )
% 'then' parts are always indented further than conditions % 'otherwise' part indented at the same level than conditions ( test1 -> test1_is_true ; test2 -> test2_is_true_and_test1_is_false ; both_are_false )
I have also seen code where 'both_are_false' is indented like:
( test1 -> test1_is_true ; test2 -> test2_is_true_and_test1_is_false ; both_are_false )
We also have code that follows your recommendations, e.g.:
mark_meta_body_spec(list(Spec), A, M) :- ( nonvar(A), A = [H|T] -> mark_meta_body_spec(Spec, H, M), mark_meta_body_spec(list(Spec), T, M) ; true ).
but I visualize its structure better in this layout (indentation helps me locate conditions more quickly than searching for '->'):
mark_meta_body_spec(list(Spec), A, M) :- ( nonvar(A), A = [H|T] -> mark_meta_body_spec(Spec, H, M), mark_meta_body_spec(list(Spec), T, M) ; true ).
If your paper convinces me that this layout is ugly, I would stop using it.
Section 3.1: Ciao code is mostly written with intercaps for variables and underscores within atoms.
Section 4: You could also mention, just as alternative approaches, lpdoc and related systems (e.g. the XSB documentation system), which predate pldoc. Note that lpdoc and the assertion language in Ciao does not only provide a formal language for types, but a larger specification language to describe more properties (which btw is mostly non-prescriptive).
For example, it is possible to describe the instantiation state before and after the execution of a predicate, it is possible to generalize changes in instantiation states (i.e. defining modes), and to describe other computational effects (i.e. determinism, cost, termination). I recognize that designing a sublanguage in Prolog to describe this is not an easy task. From an objective point of view, it is a pity that are still talking about 'arbitrary types meaningful to the reader' and 'informal types'.
I understand that all of this is out of the scope of the paper, but summarizing you could just extend 'footnote 5' to more properties than prescriptive types.
There is a problem with the notation:
%% age(+Name:atom, -Age:integer) is semidet
If at some point you expect to add formal types, which could be defined in modules, and those be prefixed with module names, then ':'/2 may be troublesome. I dislike 'is'/2, which is used for evaluation of functions.
Ciao assertions have also some problems with some operators. It would be great if we agree on a common notation that is both easy to read, write, and scalable (to not just documentation but also formal methods).
Best regards