Changes between Version 7 and Version 8 of Commentary/Rts/Conventions


Ignore:
Timestamp:
Dec 5, 2009 8:07:50 PM (6 years ago)
Author:
simonmar
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/Rts/Conventions

    v7 v8  
    5959   prefer to use them whenever possible.
    6060
    61   In addition we use ANSI-C-style function declarations and prototypes
    62   exclusively.  Every function should have a prototype; static
    63   function prototypes may be placed near the top of the file in which
    64   they are declared, and external prototypes are usually placed in a
    65   header file with the same basename as the source file (although
    66   there are exceptions to this rule, particularly when several source
    67   files together implement a subsystem which is described by a single
    68   external header file).
     61In addition we use ANSI-C-style function declarations and prototypes
     62exclusively.  Every function should have a prototype; static
     63function prototypes may be placed near the top of the file in which
     64they are declared, and external prototypes are usually placed in a
     65header file with the same basename as the source file (although
     66there are exceptions to this rule, particularly when several source
     67files together implement a subsystem which is described by a single
     68external header file).
    6969
    7070 * We use the following GCC extensions, but surround them with {{{#ifdef__GNUC__}}}:
     
    288288   don't conflict.
    289289
    290   OTOH, the gcc manual says this
    291   so maybe we should use extern inline?
    292 {{{
    293    When a function is both inline and `static', if all calls to the
    294 function are integrated into the caller, and the function's address is
    295 never used, then the function's own assembler code is never referenced.
    296 In this case, GNU CC does not actually output assembler code for the
    297 function, unless you specify the option `-fkeep-inline-functions'.
    298 Some calls cannot be integrated for various reasons (in particular,
    299 calls that precede the function's definition cannot be integrated, and
    300 neither can recursive calls within the definition).  If there is a
    301 nonintegrated call, then the function is compiled to assembler code as
    302 usual.  The function must also be compiled as usual if the program
    303 refers to its address, because that can't be inlined.
    304 
    305    When an inline function is not `static', then the compiler must
    306 assume that there may be calls from other source files; since a global
    307 symbol can be defined only once in any program, the function must not
    308 be defined in the other source files, so the calls therein cannot be
    309 integrated.  Therefore, a non-`static' inline function is always
    310 compiled on its own in the usual fashion.
    311 
    312    If you specify both `inline' and `extern' in the function
    313 definition, then the definition is used only for inlining.  In no case
    314 is the function compiled on its own, not even if you refer to its
    315 address explicitly.  Such an address becomes an external reference, as
    316 if you had only declared the function, and had not defined it.
    317 
    318    This combination of `inline' and `extern' has almost the effect of a
    319 macro.  The way to use it is to put a function definition in a header
    320 file with these keywords, and put another copy of the definition
    321 (lacking `inline' and `extern') in a library file.  The definition in
    322 the header file will cause most calls to the function to be inlined.
    323 If any uses of the function remain, they will refer to the single copy
    324 in the library.
    325 }}}
    326 
    327290 * Don't define macros that expand to a list of statements.  You could
    328291   just use braces as in:
     
    432395 * We don't care too much about your indentation style but, if you're
    433396   modifying a function, please try to use the same style as the rest
    434    of the function (or file).  If you're writing new code, a tab width
    435    of 4 is preferred.
    436 
     397   of the function (or file).  If you're writing new code, an indentation width
     398   of 4 is preferred (don't use actual tab characters, use spaces).
     399
     400 * Please write comments in English.  Especially avoid Klingon.
    437401
    438402== Source-control issues ==