[m-rev.] diff: coding_standards.html

[Zoltan Somogyi]

This has already been discussed in email and in person.

compiler/notes/coding_standards.html:
	Update the coding standard to ask for each import_module to import
	only one module even if the module is from the library.

	Update the coding standard to reflect current accepted practice
	with respect to indentation and the formatting of type definitions.

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	21 Mar 2005 05:48:05 -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,29 @@
 
 <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.
+A tab character should always mean 8 spaces;
+if a module is indented using 4 spaces per level of indentation,
+this should be indicated by four spaces,
+not by a tab with tab stops set to 4.
 
 <p>
 
-Each line should not extend beyond 79 characters.
+Files that use 8 spaces per level of indentation
+don't need any special setup.
+Files that use 4 spaces per level of indentation
+should have something like this at the top,
+even before the copyright line:
+<pre>
+	% vim: ft=mercury ts=4 sw=4 et
+</pre>
+
+<p>
+
+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 +267,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 +275,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 +398,30 @@
 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.
+
+<p>
+
+Each group of import_module items should be sorted,
+since this makes it easier to detect duplicate imports
+and missing imports.
+It also groups together the imported modules from the same package.
+There should be no blank lines between
+the imports of modules from different packages,
+since this makes it harder to resort the group
+with a single editor command.
+
+<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 +490,6 @@
 
 The file <a href="reviews.html">compiler/notes/reviews.html</a>
 contains more information on review policy.
-
-
-
 
 <hr>
 <!-------------------------->
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------