Coding Hints

The following tips are provided as an aid to writting readable, portable code. I have not made any of these up - they have all been culled from texts on programming techniques. I can provide some references if needed.

These are not laws. They can be violated. However you should have a good reason for violating these hints, and you should put a comment in your code saying why they are violated.

The hints are provided to try and help when writting code in FORTRAN(77), ANSI C and C++ under Unix (Linux), Windows NT (MS compilers) and VMS. Note that many older texts on C use KR C, not ANSI C. Note also, that C++ is in state of flux. Their is not a standard for C++. There is a Draft ANSI standard, but not all compilers comply with it. In particular, CINT has some deficiencies.

• Do not assume how many bytes of memory a variable takes. (In C/C++, you can use the sizeof operator, if you must know this.)
• Do not assume an order (big endian/little endian) in which bytes of a multi-byte variable are stored.
• Do not use short variable names (ie. use a name that has a meaning). This can be a problem in FORTRAN-77 - six characters is not very many. Note however, the g77, Fortran Powerstation, and VMS Fortran all support names longer than 6 characters. How about HP-UX fortran?
• Do not use long variable names (too many characters will cause more typos). (Many compilers will use only the first 31 characters even if they allow more.)
• Do not use GOTO. (Including FORTRAN assigned goto and conditional goto.)
• Do use structured IF statements. (ie. in FORTRAN use IF (condition) THEN ... ENDIF, and in C always use a multi statement format, if (condition) {...};
• Every file should start with a comment about what is in the file.
• Every function/subroutine should start with a comment after it's definition line, saying what the sub-program is for, and how it is to be used. (Keep comments brief, and use references if appropriate. Do not repeat anything which is written in the code itself - self-documenting code is preferable to heavily commented code.)
• Comment all global variables (and all important local variables).
• Do not change variable names between different instances of common blocks. (Also do not use equivalence statements.)
• Avoid global variables.
• Use the CFORTRAN package to interface C and FORTRAN.
• Use subroutine definitions etc. to avoid rewritting code (ignore possible run time overhead - if run-time overhead is too big, we can find otherways around it.)
• Indent program blocks:

    IF (X.GT.0) THEN
      Y = SQRT(X)
    ELSE
      Y = 0.
    ENDIF
    
    if (x>0) {
      y = sqrt(x);
    } else {
      y = 0.;
    };
    

• FORTRAN-77 does not have a SWITCH CASE type of control mechanism. In C/C++, put a break after the last case program block.
• Use function prototypes always (C++ and ANSI C requires them.)
• Use multiple source files as appropriate. (One function per file can lead to too many files. One file per project and the file is too long. Put similar things in one file, and try keep the file to 1000 lines.)
• Within a C++ class declaration, put in all sections, public:, protected: and private:, even if a section is empty.
• Give all data members an initial prefix to identify them as such. (In ROOT, all data members names start with an f. I like the prefix its.)
• Give all dummy arguments a prefix to identify them as such. (I like the prefix the.)
• All class names start with an uppercase letter. (In root it is a T.) All variable names start with a lowercase letter.