
<!--

  newcode.xml          GAP documentation

  Copyright (C) 2005,  The GAP Group

Hints for writers and referees of new code in library or packages.

-->

<Chapter Label="Chap-NewCode">
<Heading>Hints and conventions for writing &GAP; programs</Heading>

Idea: Collect hints or ideas on questions like: name clashes, functions versus
operations, declaration and implementation files, organising large sets
of data, ...
<P/>
(We certainly don't want to develop <Q>obligatory coding guidelines</Q>,
but it may be sensible to fix some unwritten conventions to reduce
clashes between the library and packages and to make the use of &GAP;
easier.)
<P/>
Such a section may also be useful for editors/referees of packages.
<P/>

<Section Label="Sect-NamingConventions">
<Heading>Naming conventions</Heading>

By convention, names of documented global variables are usually
concatenations of capitalized words, like e.g.
<C>ConjugacyClassesSubgroups</C>. Thus, words are separated by
capital letters rather than underscores.
Names of only internally used global variables are usually
written in capital letters only, and words are separated by
underscores, like e.g. <C>SHALLOWCOPY_GF2MAT</C>. <P/>

As there is only one global name space, some care has to be taken to
avoid name clashes between packages or between packages and the library.
A useful rule in this context is the following: <P/>

Names standing for general concepts can be introduced
in the library as names of wrapper functions like e.g. <C>Group</C>
or of operations or attributes.
If they are introduced in packages, they should always be used for
operations or attributes to allow other packages to install methods
as well or to declare an operation of the same name with a different
scope. <P/>

</Section>

</Chapter>

