pqc/external/flint-2.4.3/code_conventions.txt

110 lines
4.5 KiB
Plaintext
Raw Normal View History

2014-05-18 22:03:37 +00:00
Code conventions
================
Language dialect
----------------
For greater portability, the code should be ANSI C compatible where possible.
We note the following exceptions:
- Inlined functions, inlined assembly. We define alternative keywords
__asm__ and __inline__ in flint.h so that gcc allows compiling with
the flags "-ansi -pendatic" nonetheless.
Primitive types
---------------
Depending on the main interpretation of the value of a variable, where
possible the following primitive datatype should be used:
| bit counts up to a single limb | ulong |
| bit counts, multiprecision | mp_bitcnt_t |
| byte counts (strings) | size_t |
| limb counts in multiprecision integers | mp_size_t |
| limbs (unsigned/signed) | mp_limb_t/ mp_limb_signed_t |
| mp_limb_t arrays | mp_ptr/ mp_srcptr |
| ui/ si function constants | ulong/ slong |
| exponents (unsigned/signed) | ulong/ slong |
| polynomial lengths | slong |
| number of indeterminates | slong |
| row/ column indices | slong |
| precision for mpfr types | mpfr_prec_t |
The typical definitions of these in terms of primitive types are:
| mp_bitcnt_t | ulong, or ulong long |
| mp_size_t | long, or long long |
| mp_limb_t | ulong, or ulong long |
| mp_ptr | mp_limb_t * |
| mp_srcptr | const mp_limb_t * |
| slong | long or long long |
| ulong | ulong or ulong long |
Use of const
------------
Input parameters to functions should be marked const in the following cases:
* complex types that are passed by reference, e.g. fmpz_poly_t
They should not be used on output parameters or for simple types or simple
structs which are passed by value and not reference, e.g. nmod_t.
Random functions
----------------
When writing functions which produce random values the order of operands should
follow one of the following:
if the function returns its random value, the state comes first, e.g:
a = n_randint(state, n)
if the function sets its first argument to a random value, the state
comes second, e.g.
nmod_poly_randtest(poly, state, len, bits)
Conversion functions
--------------------
When naming functions which convert between objects of different modules, use
the convention module1_get_module2 and module1_set_module2, where module1 is
notionally the more complex of the two modules. E.g. fmpz_poly_get_nmod_poly.
The set function should set an object of module1 to the value of an object of
module2, and the get function should do the opposite.
Code formatting
---------------
The C code should follow the style produced by the following call to "indent",
indent -bap -blf -bli0 -cbi0 -cdw -cli4 -cs -i4 -l79 -nbad -nbc -nce -npcs -nprs -nut -pmt -psl -saf -sai -saw -sbi0 -ss -ts4
which is explained as follows:
-bap Force blank lines after procedure bodies
-blf Put braces on line following function definition line
-bli0 Indent braces 0 spaces
-cbi0 Indent braces after a case label 0 spaces
-cdw Cuddle while of do {} while
-cli4 Case label indent of 4 spaces
-cs Put a space after a cast operator
-i4 Set indentation level to 4 spaces
-l79 Set maximum line length for non-comment lines to 79
-nbad Do not force blank lines after declarations
-nbc Do not force newlines after commas in declarations
-nce Do not cuddle else
-npcs Do not put a space after the function in function calls
-nprs Do not put a space after every ( and before every )
-nut Use spaces instead of tabs
-pmt Preserve access and modificaion times on output files
-psl Put the type of a procedure on the line before its name
-saf Put a space before each for
-sai Space after each for
-saw Space after every while
-sbi0 Indent braces of a struct, union or enum 0 spaces
-ss On one-line for and while statements, for a blank before ;
-ts4 Set tab size to 4 spaces