[m-rev.] proposed addition to coding standards

[Fergus Henderson]

I have noticed that while most files in the Mercury system are written
in top-down order, others are written in bottom-up order.

Top-down ordering is usually a lot easier to read and understand than
bottom-up ordering, so I propose that we specify this in our coding
guidelines.

----------

Estimated hours taken: 0.25
Branches: main

compiler/notes/coding_standards.html:
w3/information/developers/c_coding_standard.html:
	Specify that code should generally be order top-down, not bottom-up.

Workspace: /mnt/ceres/home/ceres/fjh/mercury
Index: compiler/notes/coding_standards.html
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/notes/coding_standards.html,v
retrieving revision 1.9
diff -u -d -r1.9 coding_standards.html
--- compiler/notes/coding_standards.html	22 Oct 2003 06:02:29 -0000	1.9
+++ compiler/notes/coding_standards.html	12 Nov 2003 13:34:25 -0000
@@ -286,11 +286,16 @@
 
 should be used.
 
+<h2> Structuring </h2>
+
+Code should generally be arranged so that procedures (or types, etc.)
+are listed in top-down order, not bottom-up.
+
 <p>
-	
-At a higher level, code should be grouped into bunches of related
-predicates, functions, etc., and sections of code that are conceptually
-separate should be separated with dashed lines:
+
+Code should be grouped into bunches of related predicates, functions,
+etc., and sections of code that are conceptually separate should be
+separated with dashed lines:
 
 <pre>
 
Index: w3/information/developers/c_coding_standard.html
===================================================================
RCS file: /home/mercury1/repository/w3/information/developers/c_coding_standard.html,v
retrieving revision 1.3
diff -u -d -r1.3 c_coding_standard.html
--- w3/information/developers/c_coding_standard.html	4 Nov 2002 13:12:30 -0000	1.3
+++ w3/information/developers/c_coding_standard.html	12 Nov 2003 13:34:05 -0000
@@ -101,6 +101,10 @@
 <li>	Definitions of functions.
 </ul>
 
+Within each section, items should generally be listed in top-down order,
+not bottom-up.  That is, if foo() calls bar(), then the definition of
+foo() should precede the definition of bar().
+
 <h4>
 1.2.2. Header files</h4>
 

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------