[m-rev.] for review: change coding standards

[Julien Fischer]

Estimated hours taken: 1
Branches: main

This is a follow-up to the thread I started on mercury-developers
a week or so ago.

compiler/notes/coding_standards.html:
	Modify the coding standards to specify how descriptive
	comments for library procedures should be placed.
	By fixing a style (hopefully) the library reference guide
	should have a more consistent appearance

	Specify that predmode syntax should be used in preference
	to a separate mode declaration if a predicate has only
	one mode.

	Specify that descriptive comments for procedures should
	ideally specify under which conditions the procedure
	can fail (if it can) or throw an exception.

Julien.

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	1 Apr 2004 04:48:13 -0000
@@ -46,7 +46,9 @@

 Each predicate other than trivial access predicates should have
 a short comment describing what the predicate is supposed to do,
-and what the meaning of the arguments is.
+and what the meaning of the arguments is.  Ideally this description
+should also note any conditions under which the predicate can fail
+or throw an exception.

 <p>

@@ -187,6 +189,10 @@

 <p>

+Predicates that have only one mode should use predmode declarations
+rather than having a separate mode declaration.
+
+<p>
 If-then-elses should always be parenthesized,
 except that an if-then-else that occurs as the else
 part of another if-then-else doesn't need to be parenthesized.
@@ -361,6 +367,44 @@
 can also be used to indicate divisions into major sections.
 Note that these dividing lines should not exceed the 79 character limit
 (see above).
+
+<h2> Standard Library Predicates </h2>
+
+The descriptive comment for any predicate or function that occurs in
+the interface of a standard library module must be positioned above
+the predicate/function declaration.  It should be indented one
+level further than the predicate or function declaration.  There must
+be a blank comment between the description and the predicate/function
+declaration.
+
+For example
+
+<pre>
+
+		% Description of predicate foo.
+		%
+	:- pred foo(...
+	:- mode foo(...
+</pre>
+
+A group of related predicate, mode and function declarations may be grouped
+together under a single description provided that it is formatted as above.
+
+For example
+
+<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).
+
+</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 a uniform appearance.

 <h2> Testing </h2>


--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------