[m-dev.] proposed change to the coding style document

[Zoltan Somogyi]

This mostly codifies what we do now, except for the one about
:- import_module of library files. Any comments?

Zoltan.

cvs diff: Diffing .
Index: coding_standards.html
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/compiler/notes/coding_standards.html,v
retrieving revision 1.15
diff -u -b -r1.15 coding_standards.html
--- coding_standards.html	7 Mar 2005 01:05:35 -0000	1.15
+++ coding_standards.html	19 Mar 2005 06:01:43 -0000
@@ -125,7 +125,7 @@
 Use state variables for threading the IO state etc.  The conventional IO
 state variable name is <code>!IO</code>.
 
-<h2> Error Handling </h2>
+<h2> Error handling </h2>
 
 <p>
 
@@ -146,17 +146,20 @@
 
 <p>
 
-Error messages should follow a consistent format.  For compiler error
-messages, each line should start with the source file name and line
-line number in "%s:%03d: " format (but use prog_out__write_context --
-we may want to change this format later, e.g. to include column
-numbers).  Compiler error messages should be complete sentences; they
+Error messages should follow a consistent format.
+For compiler error messages, each line should start
+with the source file name and line number in "%s:%03d: " format.
+Compiler error messages should be complete sentences; they
 should start with a capital letter and end in a full stop.  For error
 messages that are spread over more than one line (as are most of them),
 the second and subsequent lines should be indented two spaces.  If the
 `--verbose-errors' option was set, 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
+only if there is no way to add the capability you require to error_util.m.
 
 <p>
 
@@ -174,15 +177,14 @@
 
 <p>
 
-Code should be indented consistently.
-Tabs should be every 8 spaces.
-Indentation should be one tab per level of indentation.
-except for highly intended code which may be
-indented at 4 spaces per level of indentation.
+Each module should be indented consistently,
+with either 4 or 8 spaces per level of indentation.
+The indentation should be consistently done,
+either only with tabs or only with spaces.
 
 <p>
 
-Each line should not extend beyond 79 characters.
+No line should extend beyond 79 characters.
 The reason we don't allow 80 character lines is that
 these lines wrap around in diffs,
 since diff adds an extra character at the start of each line.
@@ -250,7 +252,7 @@
 
 <p>
 
-Type definitions should be formatted in the following style:
+Type definitions should be formatted in one of the following styles:
 
 <pre>
 	:- type my_type
@@ -258,6 +260,12 @@
 				some_other_type	% comment explaining it
 			).
 
+	:- type my_struct --->
+		my_struct(
+			field1,			% comment explaining it
+			...
+		).
+
 	:- type some_other_type == int.
 
 	:- type foo
@@ -375,7 +383,22 @@
 Note that these dividing lines should not exceed the 79 character limit
 (see above).
 
-<h2> Standard Library Predicates </h2>
+<h2> Module imports </h2>
+
+Each group of :- import_module items should list only one module per line,
+since this makes it much easier to read diffs
+that change the set of imported modules.
+In the compiler, when e.g. an interface section imports modules
+from both the compiler and the standard library,
+there should be two groups of imports,
+the imports from the compiler first and then the ones from the library.
+For the purposes of this rule,
+consider the modules of mdbcomp to belong to the compiler.
+Each group of import_modules should be sorted,
+since this makes it easier to detect duplicate imports
+and missing imports.
+
+<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
@@ -444,9 +467,6 @@
 
 The file <a href="reviews.html">compiler/notes/reviews.html</a>
 contains more information on review policy.
-
-
-
 
 <hr>
 <!-------------------------->
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------