[m-rev.] Website, For review: Update the coding standard on the website.

[Paul Bone]

On Thu, Jan 02, 2014 at 12:26:55PM +1100, Julien Fischer wrote:
>> @@ -495,6 +495,12 @@ the reference manual for the standard library
>> is automatically generated from the module interfaces,
>> and we want to maintain a uniform appearance as much as is possible.
>>
>> +Traditionally most declarations, definitions and calls in the standard
>> +library were module qualified.
>> +This is no-longer required by the coding standard.
>> +The exception to this is where disambiguation is useful for anyone reading
>> +the code or for the compiler.
>
> It would be more concise to simply say what the coding standard requires
> rather than attempting to document what they past practice may (or may
> not) have been.

I'll repharse my changes.

> Does the omission of module qualification extend to the comments
> documenting predicates?  For example, is it (as now):
>
>         % list.sort_and_remove_dups(List0, List):
>         %
>         % List is List0 sorted with the second and subsequent occurrence of
>         % any duplicates removed.
>         %
>     :- pred list.sort_and_remove_dups(list(T)::in, list(T)::out) is det.
>
> or:
>
>         % sort_and_remove_dups(List0, List):
>         %
>         % List is List0 sorted with the second and subsequent occurrence of
>         % any duplicates removed.
>         %
>     :- pred list.sort_and_remove_dups(list(T)::in, list(T)::out) is det.
>

In this case, yes this prefix should be removed because it's obvious from
the context of reading the documentation of list.m.

The kind of change (is this really a change?) that I'm looking for is just
to use common sense a bit more with these qualifiers.  Don't add them by
default, but do add them when they're not obvious.

It's worth noting that the module of a predicate in a predicate call (or
function) is less obvious from context.  So these should be qualified when
that helps disambiguation.  An example of this is most code that Zoltan
writes. 


> (Another issue with above example is that some modules quote arguments
> like List and List0 in their predfunc descriptions and others do not.)

I propose that we don't quote these, at least for now.  We should revisit it
if we ever create a better API documentation system (see: Javadoc or
doxygen).

> I think trying to promote consistency across the standard library,
> particulary the parts that get pulled into the libary reference guide,
> is a good thing, but I would like to see a more detailed proposal that
> addresses various other inconsistencies.  For example,

I'm not sure if we need rules about some of these, but I'm happy with rules
about others.

> - if a predicate or function throws an exception how is that described
>   to the user.  Currently, various wordings are used to descibe this.
>   (e.g. "Aborts if ...", "Calls error/1 if ...", "Throws an exception if
>   ...", "It is an error if ...")

"Throws an exception if ..." is my favorite, it seems clearer about what the
concequence is.

>
> - for predicates where the are multiple modes, in what order should they
>   be listed.  (Actually, we already mostly follow the convention that
>   it's in increasing order of uniqueness followed by determinism, but
>   that's not documented anywhere.)

Fine by me.

> - Should variables in predicate descriptions be quoted?
>
> - In descriptions, "True iff ..." vs. "Succeeds iff ...".
>

I probably prefer "True iff ..." as it's more declarative.  But this is
dependent on the use/context of such a comment.


-- 
Paul Bone
http://www.bone.id.au