Guidelines for the zealots

The CodingStyle used in an application can lead to various heated debates. To avoid those in future, the SpamAssassin team tried to come to a compromise. Not everybody likes every single detail but sometimes one has to bite the bullet to avoid long discussions

Perl CodingStyle

Mostly quite sensible perl stuff. Minor differences from what's considered "normal":

Formatting

The main difference between our style and the standard Perl style is that we use an indentation level of 2.

Braces and Parentheses

elsif and else are uncuddled, no spaces on the inside of paretheses, and try to avoid one-liner conditionals that require braces. If braces are needed, use multiple lines. Open braces should appear on the same line of the condition, unless it's a multiple line condition. For example:

  if ($foo) {
     do_foo();
  }
  elsif ($bar_really_long_condition_that_lasts_longer_than_40_columns &&
         $foo_really_long_condition_that_lasts_longer_than_40_columns)
  {
     do_bar();
  }
  else {
     do_else();
  }

(status of this guideline: proposed by DanielQuinlan. everyone happy with it?)

Function Arguments

Use @_ rather than shift if possible. For example:

  sub foo {
    my ($foo, $bar) = @_;

instead of

  sub foo {
    my $foo = shift;
    my $bar = shift;

(status of this guideline: proposed by DanielQuinlan. everyone happy with it?)

Accessors

We don't use perl-style accessors very frequently (ie.

  sub foo {
    my ($self, $val) = @_;
    if (defined $val) { $self->{foo} = $val; } else { return $val; }
  }

since these can have side-effects if your code accidentally calls

 $obj->foo($newval); 

and $newval is undef. Instead, the more wordy Java/C++ style is preferred:

  sub get_foo { my ($self) = @_; return $val; }
  sub set_foo { my ($self, $val) = @_; $self->{foo} = $val; }

(status of this guideline: proposed by JustinMason. everyone happy with it?)

Return Values From Functions

Returns should be explicit, instead of implicit, for clarity:

  sub foo { ...stuff...; $val = 1; return $val; }

instead of

  sub foo { ...stuff...; $val = 1; }

reason: in the latter, $val is returned, but it's not explicit and not obvious. A later change could result in code being added after the assignment to $val, since it's not clear that the value is returned by the function.

(status of this guideline: proposed by JustinMason. everyone happy with it?)

C CodingStyle

In our C code we took the easiest way and adopted the [http://www.apache.org/dev/styleguide.html Apache Developers' C Language Style Guide].