Tech:Coding Standards

From Cyclopath

Please follow these conventions when working on Cyclopath code. Consistency is important and saves bugs.

FIXME: clean up, organize, expand.

• Copyright notice: Each file needs to begin with the copyright notice. If you are an external developer, feel free to add yourself to this.
• Naming:
  • Name methods and variables most-significant-first. Often this means noun, verb order rather than verb, noun which most project use. Example: say features_add(), not add_features().
  • Use underscores to separate words.
  • Name classes like Here_Is_a_Class (title case) and variables like here_is_a_variable (lower case).
  • Absolutely no StudlyCaps unless necessary to follow existing style in some interface or standard.
• Order within code files: Divide ActionScript files into the following sections, in this order:

  // *** Static variables
  // *** Instance variables
  // *** Constructor
  // *** Static methods
  // *** Getters and setters
  // *** Event handlers
  // *** Instance methods
  

  Code in other languages should be ordered similarly.

• Place methods in alphabetical order within sections.
• Spacing and formatting: Format your code like so:

  // Discard features and their dependent objects. If rectangle r is not
  // null, discard only features which do not intersect r. 
  public function features_discard(r:Dual_Rect) :void
  {
     var i:int;
     var discard_ct:int;
     var f:Feature;
     var crect:Rectangle;
  
     discard_ct = 0;
     // Iterate downwards because it is cheaper to remove the last child
     // than middle children??? (Speculation only, not tested!)
     for (i = this.numChildren - 1; i >= 0; i--) {
        f = (this.getChildAt(i) as Feature);
        crect = f.bbox_get(this);
        if (f.discardable
            && (r === null || !r.intersects_fgrect(crect))) {
           f.cleanup(i);
           this.removeChildAt(i);
           discard_ct++;
        }
     }
     //trace('Discarded ' + discard_ct + ' features');
  }
  
  // Label all features which need labeling
  public function features_label() :void
  {
     var i:int;
  
     for (i = 0; i < this.numChildren; i++)
        (this.getChildAt(i) as Geofeature).label_maybe();
  }
  

  A few specific notes:
  • Three spaces per indent level.
  • Absolutely no tab characters.
  • Use single quotes unless double quotes are necessary for a specific reason (SQL code being a common one).
  • No lines over 79 characters, except in exceptional circumstances. Don't hesitate to introduce a temp variable to accomplish this.
  • Brackets for one-line blocks are optional.
  ActionScript-specific things:
  • If a method requires no comment, put an empty one to keep the spacing.
  • Put all variable declarations at the beginning of the method, since if you don't the compiler will silently move them.
  Python-specific things:
  • Order of imports: Put system imports in a group before project imports, and alphebetize each group. An exception is conf: because it sets sys.path, this module must be imported before other project imports, and sometimes before system ones as well.
• Control statement formatting:
  • When mixing operators of different precedence, use parenthesis to improve readability and reduce the likelihood of typos.
  • For short variable names, this is acceptable:

    if (x == 1 && y == 2) { }

    But for long variable names, consider using parenthesis:

    if ((my_long_variable !== null) && (some_other_var == third_var)) { }

  • When using negation on single variables, simple notation is acceptable:

    if (!x && !y) { }

    But when applying negation to a function call, use parenthesis:

    if (!(foo.bar.baz())) { }

[edit] Formatting function arguments

This is OK:

G.arrow_tip_draw(g, ex - dx * skip_end, ey - dy * skip_end,
                 dx, dy, tipsize, tipsize, color, alpha);

This is OK:

G.arrow_tip_draw_holy_crap_this_fcn_is_long_omgomgomgomgomg(
   g, ex - dx * skip_end, ey - dy * skip_end, dx, dy);

(though please don't name your functions like that...)

This is not OK:

G.arrow_tip_draw(
   g, ex - dx * skip_end, ey - dy * skip_end);

i.e.: put arguments in a "box" lining up to the right of the opening paren, except in cases where this ends up really awkward or it makes the call into 4 or more lines.