mirror of
https://github.com/Mercury-Language/mercury.git
synced 2025-12-20 08:19:28 +00:00
6e8bbbe46e
Estimated hours taken: 0.25 compiler/notes/CODING_STANDARDS: Add some information about committing changes. (In particular, when adding new files, don't forget to check the permissions!)
114 lines
4.2 KiB
Plaintext
114 lines
4.2 KiB
Plaintext
Documentation
|
|
-------------
|
|
|
|
Each module should contain header comments which state
|
|
the module's name, main author(s), and purpose, and
|
|
give an overview of what the module does, what are the
|
|
major algorithms and data structures it uses, etc.
|
|
|
|
Each type or predicate that is exported from a module should have
|
|
sufficient documentation that it can be understood without reference
|
|
to the module's implementation section.
|
|
|
|
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.
|
|
|
|
There should be a comment for each field of a structure saying
|
|
what the field represents.
|
|
|
|
Any user-visible changes such as new compiler options or new
|
|
features should be documented in appropriate section
|
|
of the Mercury documentation (usually the Mercury User's Guide
|
|
and/or the Mercury Reference Manual).
|
|
|
|
|
|
Naming
|
|
------
|
|
|
|
Variables should always be given meaningful names,
|
|
unless they are irrelevant to the code in question.
|
|
For example, it is OK to use single-character names
|
|
in an access predicate which just sets a single
|
|
field of a structure, such as
|
|
|
|
bar_set_foo(Foo, bar(A, B, C, _, E), bar(A, B, C, Foo, E)).
|
|
|
|
Variables which represent different states or different versions
|
|
of the same entity should be named Foo0, Foo1, Foo2, ..., Foo.
|
|
|
|
Predicates which get or set a field of a structure or ADT should
|
|
be named bar_get_foo and bar_set_foo respectively, where bar
|
|
is the name of the structure or ADT and foo is the name of the field.
|
|
|
|
|
|
Coding
|
|
------
|
|
|
|
Your code should make as much reuse of existing code as possible.
|
|
"cut-and-paste" style reuse is highly discouraged.
|
|
|
|
Code should check for both erroneous inputs from the user and also
|
|
invalid data being passed from other parts of the Mercury compiler.
|
|
Calls to error/1 should always indicate an internal software error, not
|
|
merely incorrect inputs from the user.
|
|
|
|
Your code should be efficient. Performance is a quite
|
|
serious issue for the Mercury compiler.
|
|
|
|
|
|
Layout
|
|
------
|
|
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 line should not extend beyond 80 characters,
|
|
unless this is necessary due to the use of long string literals.
|
|
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).
|
|
The condition of an if-then-else can either be on the same
|
|
line as the opening parenthesis and the `->', or it can
|
|
be on a line of its own.
|
|
|
|
Sections of code that are conceptually separate should be
|
|
separated with dashed lines:
|
|
|
|
%---------------------------------------------------------------------------%
|
|
|
|
|
|
Testing
|
|
-------
|
|
|
|
Every change should be tested before being committed.
|
|
The level of testing required depends on the nature of the change.
|
|
If this change fixes an existing bug, and is not likely to introduce
|
|
any new bugs, then just compiling it and running some tests
|
|
by hand is sufficient. If the change might break the compiler,
|
|
you should run a bootstrap check (using the `bootcheck' script)
|
|
before committing. If the change means that old versions of
|
|
the compiler will not be able to compile the new version of the
|
|
compiler, you must notify all the other Mercury developers.
|
|
|
|
In addition to testing before a change is committed, you need to make
|
|
sure that the code will not get broken in the future by adding tests to
|
|
the test suite. Every time you add a new feature, you should add some
|
|
test cases for that new feature to the test suite. Every time you fix
|
|
a bug, you should add a regression test to the test suite.
|
|
|
|
|
|
Committing changes
|
|
------------------
|
|
|
|
Before committing a change, you should get someone else to review your
|
|
changes. Normally this should be done by sending the output of `cvs
|
|
diff -u' to fjh@cs.mu.oz.au, together with a description of the changes
|
|
for the CVS log. If you have added any new files or directories, you
|
|
*must* check the group-id and permissions of the newly created files or
|
|
directories in the CVS repository. Files should be readable by group
|
|
mercury and directories should be both readable and writeable by group
|
|
mercury.
|
|
|