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


Ignore:
Timestamp:
Dec 5, 2009 8:07:50 PM (4 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 ==