Coding Guidelines

When coding for Dia, it makes life easier for everyone if we follow the same coding guidelines.  Poorly written/formatted/documented code is more likely to be returned to sender, wasting time for all parties.  Below, I describe the guidelines that I as maintainer would like to see followed.

Dia was not originally written with strong guidelines in mind, and it shows.  The code style varies based on programmer, task, and mood, and very little is documented.  This is not an excuse to write new code crappily.

The base of the coding guidelines are Sun's guidelines for Java, even though Dia is written in C.  Syntactically, there's enough overlap that it makes sense.  Sun's guidelines are mostly on a syntactic level; here are some highlights:

  • Never elide brackets (curly braces { }); use parentheses when any confusion is possible.
  • Always document functions and global variables (using Javadoc style).
  • Always indent four spaces and wrap nicely before 80 characters.
  • Put spaces around all operators and after keywords and separators (semicolon and comma).

For in-function variables and parameters, use all lowercase and underscores.  For constants and macros, use all uppercase and underscores.  No Hungarian notation, please.  For types and struct names, use camel-case.

For GNU tool compatibility, function declarations should have the return type on one line, then the name and parameters, then the start bracket on a line by itself:

/** Checks if two reals are the same.
 *  @param r1 The first real number.
 *  @param r2 The second real number.
 *  @returns True if the two numbers differ by less than a very small constant.
is_same(real r1, real r2)
    return fabs(r1 - r2) < MIN_REAL_DIFFERENCE;

Some C-specific warnings:

  • Never use //-style comments.
  • Always put parentheses around uses of variables in macro definitions.
  • Look at the compiler warnings and try to eliminate them by improving the code.

Apps/Dia/CodingGuidelines (last edited 2013-08-09 00:08:16 by WilliamJonMcCann)