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

[Julien Fischer]

On Wed, 25 Dec 2013, Paul Bone wrote:

> For review by Julien.  This is something I implicitly suggested and Julien
> also seems to agree with.  Any other comments are welcome.  Thanks.
>
> Website change:
> Update the coding standard on the website.
>
> Update the coding standard to say that we no-longer need to module qualify
> the declarations, definitions and uses of predicates and functions
> throughout the standard library, except where this is used for
> disambiguation.
>
> development/developers/coding_standards.html:
>    As above.
> ---
> development/developers/coding_standards.html | 14 ++++++++++----
> 1 file changed, 10 insertions(+), 4 deletions(-)
>
> diff --git a/development/developers/coding_standards.html b/development/developers/coding_standards.html
> index e1c5565..39b4a76 100644
> --- a/development/developers/coding_standards.html
> +++ b/development/developers/coding_standards.html
> @@ -164,7 +164,7 @@ you should print out additional text explaining in detail
> what the error message means and what the likely causes are.
> The preferred method of printing error messages
> is via the predicates in error_util.m;
> -use prog_out__write_context and io__write_strings
> +use prog_out.write_context and io.write_strings
> only if there is no way to add the capability you require to error_util.m.
>
> <p>
> @@ -291,7 +291,7 @@ like this:
>
> <pre>
> :- pragma foreign_proc("C",
> -        int__to_float(IntVal::in, FloatVal::out),
> +        to_float(IntVal::in, FloatVal::out),
>         [will_not_call_mercury, promise_pure],
> "
>         FloatVal = IntVal;
> @@ -485,8 +485,8 @@ For example:
> 		% Insert a new key and corresponding value into a map.
> 		% Fail if the key already exists.
> 		%
> -	:- func map.insert(map(K, V), K, V) = map(K, V).
> -	:- pred map.insert(map(K, V)::in, K::in, V::in, map(K, V)::out) is det.
> +	:- func insert(map(K, V), K, V) = map(K, V).
> +	:- pred insert(map(K, V)::in, K::in, V::in, map(K, V)::out) is det.
>
> </pre>
>
> @@ -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.

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.

(Another issue with above example is that some modules quote arguments
like List and List0 in their predfunc descriptions 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,

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

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

- Should variables in predicate descriptions be quoted?

- In descriptions, "True iff ..." vs. "Succeeds iff ...".

Cheers,
Julien.