[m-dev.] for discussion: coding standards and the library reference manual

[Ralph Becket]

Julien Fischer, Tuesday, 23 March 2004:
> 
> Index: coding_standards.html
> ===================================================================
> RCS file: /home/mercury1/repository/mercury/compiler/notes/coding_standards.html,v
> retrieving revision 1.12
> diff -u -r1.12 coding_standards.html
> --- coding_standards.html	12 Jan 2004 12:06:31 -0000	1.12
> +++ coding_standards.html	23 Mar 2004 05:59:34 -0000
> @@ -362,6 +362,51 @@
>  Note that these dividing lines should not exceed the 79 character limit
>  (see above).
> 
> +<h2> Standard Library Predicates </h2>
> +
> +Any predicate or function that occurs in the interface of a standard
> +library module must have a brief comment describing what it does.
> +Ideally this description should note any conditions under which the
> +predicate can fail or throw an exception.
> +
> +The comment must be positioned directly above the predicate, as follows:
> +
> +<pre>
> +
> +		% Description of predicate foo.
> +	:- pred foo(...
> +	:- mode foo(...
> +	:- mode foo(...
> +</pre>
> +
> +In some cases it may be clearer to place a blank comment between the
> +description and the predicate/function declaration, as follows:
> +
> +<pre>
> +
> +		% Description of predicate foo.
> +		%
> +	:- pred foo(...
> +	:- mode foo(...
> +</pre>

I think the extra blank comment line should be mandatory.  It genuinely
improves readability.

> +A group of related predicate, mode and function declarations may be grouped
> +together under a single description provided that it is formatted as above.
> +
> +<pre>
> +
> +		% Insert a new key and corresponding value into a map.
> +		% Fail if the key already exists.
> +	:- pred map.insert(map(K, V)::in, K::in, V::in, map(K, V)::out) is det.
> +	:- func map.insert(map(K, V), K, V) = map(K, V).

See above re: blank comment line!

> +
> +</pre>
> +
> +The reason for using this particular style is that the reference manual for
> +the standard library is automatically generated from the module interfaces
> +and we want, as much as is possible, to maintain an uniform appearance.
> +

Otherwise, that looks fine.

-- Ralph
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------