Coding Standards and Formatting

Coding standards

Here's the list we try to follow :

  1. Short method bodies, hopefully five lines or less.
  2. No final methods. People hack their test tools in wierd and wonderful ways.
  3. No type hinting. So much of SimpeTest is unit tested, that type hints don't currently pay their way.
  4. All object variables are private. Those currently in the code base that aren't, should be. Exceptions are fluent interfaces.
  5. ClassLikeThis, methodLikeThis(), $variables_like_this.
  6. No abbreviations in names, so $parameter rather than $param. Acronyms are allowed if they are industry standard. We tend to camel case them, e.g. parseXml().
  7. We prefer "get"/"set" prefix for accessors, e.g. getMyAttribute(). The exception is for fluent interfaces. This preference is mainly historical though, and could be dropped. Ruby coding standards are superceding Java ones these days, and "get" isn't used in that environment.
  8. Accessors even when a subclass calls a superclass.
  9. Don't be afraid of long class and method names. The exception is the use of $i as a loop variable. A lot of people viewing the code are casual passers by and won't know any secret conventions.
  10. "Simple" as a class name prefix unless it really pollutes the visible domain language. No other namespace prefixing unless there is known library clash in the wild.
  11. Eric Evans domain driven design style rather than pure XP/TDD. That is, slight over design in order to make concepts clear.

Obviously these reflect Marcus Bakers' average coding style over several projects and programming languages.

Is should also be obvious that the code is riddled with exceptions to these rules :).

Code formatting

Please no dangling brace style. No blank lines in methods. So not...

class MyClass
{
    function aMethod()
    {
        stuff();
     
        more stuff();
    }
}

It wastes vertical space and is a hangover from long declarations in C++. Rather this...

class MyClass {
    function aMethod() {
        stuff();
        more stuff();
    }
}

White space to me should separate something, such as a method or class. If you feel the need to add space within a method body, just break the code up into separate methods. The exception is test code, which can contain a lot of mock set up. It's still discouraged though.

By popular demand, all functions and methods are docblocked. Private variables are not (the extra clutter is not worth it). The only docblock attributes we require are @return and @param as some IDE's use them. Please take the time to write a human friendly comment. Imagine you are chatting to a fellow SimpleTest user and they ask the most obvious question about that variable.