Commit f8a7cb63 authored by Jurriën Stutterheim's avatar Jurriën Stutterheim

Add section about imports in dcl files to STANDARDS.txt


git-svn-id: https://svn.cs.ru.nl/repos/clean-platform/trunk@220 2afc29ad-3112-4e41-907a-9359c7e6e986
parent 6d5cde74
The following guidelines should be adhered to when developing libraries for
the Clean Platform library collection.
The following guidelines should be adhered to when developing libraries for the
Clean Platform library collection.
== Type names ==
The names of types should be clear and informative, and should always start with a capital.
If the name of a type consists of multiple words, each new word should start with a capital.
The constructors of a type should also start with a capital. Whenever the name is an abbreviation
the abbreviation should be written using only capitals (e.g. GUI,SQL,HTTP).
The names of types should be clear and informative, and should always start
with a capital. If the name of a type consists of multiple words, each new
word should start with a capital. The constructors of a type should also start
with a capital. Whenever the name is an abbreviation the abbreviation should be
written using only capitals (e.g. GUI,SQL,HTTP).
== Function names ==
Function names should *not* start with a capital, but when a function consists of multiple words,
each new word, except the first one should start with a capital. By starting types and constructors
with a capital and, functions without one, the difference between a constructor and a function
is immediately clear for the reader of a program.
Function names should *not* start with a capital, but when a function consists
of multiple words, each new word, except the first one should start with a
capital. By starting types and constructors with a capital and, functions
without one, the difference between a constructor and a function is immediately
clear for the reader of a program.
== Module names ==
For modules, the same guidelines apply as for naming types. Names should be informative and
preferably short. When a library module is not meant for direct imports by end users,
but should only used by experts in modules that for example provide a more friendly interface,
you should prefix the name of that module with an underscore character.
For modules, the same guidelines apply as for naming types. Names should be
informative and preferably short. When a library module is not meant for direct
imports by end users, but should only used by experts in modules that for
example provide a more friendly interface, you should prefix the name of that
module with an underscore character.
== Argument order ==
While there are no hard demands on the order in which you specify the arguments of functions,
there are two rules which make your functions easier to use and somewhat more clear:
While there are no hard demands on the order in which you specify the arguments
of functions, there are two rules which make your functions easier to use and
somewhat more clear:
* State representing arguments such as the common *World type argument, should be at
the end of the argument list.
* Arguments which are used as "options" in some way should be at the beginning of
the arguments. This makes it easy to pass in options by currying.
* State representing arguments such as the common *World type argument,
should be at the end of the argument list.
* Arguments which are used as "options" in some way should be at the
beginning of the arguments. This makes it easy to pass in options by
currying.
== Comments ==
A concise description of the purpose of a function and the meaning of its input and output
parameters should be present in the .dcl file for all exported functions. Comments are specified
as follows:
A concise description of the purpose of a function and the meaning of its input
and output parameters should be present in the .dcl file for all exported
functions. Comments are specified as follows:
/**
* This function is the identity.
......@@ -39,8 +44,24 @@ as follows:
id :: a -> a
id x = x
The @param notation (similar to JavaDocs) can be used to clarify the arguments separately.
The @param notation (similar to JavaDocs) can be used to clarify the arguments
separately.
== Layout ==
Whitespace and new lines can be used to format code nicely. When tabs are used for alignment, they are
considered to be fixed to four spaces.
Whitespace and new lines can be used to format code nicely. When tabs are used
for alignment, they are considered to be fixed to four spaces.
== Exporting functions and types ===
Definition modules (.dcl) must be very specific about the modules they import
because everything imported in a definition module is exported as well,
increasing the chance of name collisions. To minimize the chance for
collisions, adhere to the following conventions:
* Explicitly import the types and classes you need for specifying the type
signatures by using the "from ... import ..." notation.
* Only ever import an entire module with the "import ..." notation if you
really truly want to re-export the entire module.
Implementation modules can be more liberal with what they import.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment