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

[Julien Fischer]

Hi Paul,

On Mon, 13 Jan 2014, Paul Bone wrote:

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

You could even try rephrasing them ;-)

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

That's fine by me, except the coding standard doesn't address the issue
and most of the existing library modules do the exact opposite.  I
suggest that as part of you change you extend with an example of the
style and formatting that is wanted.

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

My point here is that the some existing modules already do quote them
and others do not.

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

No it isn't, because in many cases the descriptions don't say *what*
type of exception is thrown.  My preference here would be to use

    "Aborts if ..."

to mean that an exception of type software_error/1 is thrown, and
otherwise say:

    "Throws an exception of type foo/N if ..."

(The point is of course that the coding standard needs to actually
say that.)

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

As I said, we already (mostly) do it -- it just needs to be documented
as such.

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

Actually, based on the current library modules it seems to be dependent
on which developer wrote the comment!

Cheers,
Julien.