CodeStandards

Web-CP is a large project incorporating many modules, a web-based frontend and a command line backend it also has to work with system services like Apache, Lighttpd, Bind, FTP servers etc. In order to maintain such a substantial codebase (albeit not huge) we must enforce code standards. There is currently a lot of HTML use in web-cp and badly written, hard to read code intertwined with HTML is one of the worst things a developer can meet in code maintainance.

When writing any code for web-cp you must follow the requirements below if you want it to be accepted for inclusion into the codebase.

Rule 1 - Whitespace

When writing a function or conditional statement whitespace must be used to ensure code readability. All code must follow the same rules about whitespace so that it is easy to read from top to bottom.

A) There should always be one space on either side of a token in expressions, statements etc. The only exceptions are commas (which should have one space after, but none before), semi-colons (which should not have spaces on either side if they are at the end of a line, and one space after otherwise). Functions should follow the rules laid out already, i.e. no spaces between the function name and the opening bracket and no space between the brackets and the arguments, but one space between each argument. Example:

  // good
    $var = some_function($param1, $param2); $var++;
  // bad
    $var=some_function( $param1,$param2 );$var ++;

B) Use tabs for indentation of code blocks. The reason is very simply, people prefer different indentation widths and with tabs, it’s configurable. Most editors allow you to choose if you want 2, 4, 8 or whatever spaces as tabs. Using tabs doesn’t force this. Some people claim that code will look different (and even broken) because of the different tab widths, but this is in fact desirable. If you write your code in a correct manner, it will look correct with whatever configuration someone has.

C) Use spaces for alignment. Alignment is NOT the same as indentation. The following example should show what I mean. (· means a space, » means a tab)

  function example($variable1,
    ·················$variable2) {
      »  if(($variable1 == $variable2) ||
      »  ···some_condition()) {
      »    »  return true;
      »  }
      »   return false;
    }

D) If a function definition or expression will not easily display on one line then continue it on the next, this makes it extremely easy to see all the parameters a function has. When continuing to the next line follow rule C above. Example:

  // good
    if ($variable_ten == $variable_eleven && $condition2 = false
            && $variable2 > $variable_three && variable14 == 4 && $client_ip = "10.0.0.1")

  // bad
    if ($variable_ten == $variable_eleven && $condition2 = false && $variable2 > $variable_three && variable14 == 4 && $client_ip)

Rule 2 - Comments

I've seen so many variations in web-cp its unbeliveable almost but it seems that the following convention has appeared so it must be followed.

A) Use "//" style comments in main code declarations and function headers. When commenting code place a comment above the peice of code that it refers to, not by the side of it, the exception is variable declarations which can have comments next to them as long as they are only very short (two to four words) giving the variable's purpose.

B) Functions should always have a comment above them stating what they do. This should include parameters. For example:

  // Commit - Order the backend to perform some action
  //   $action: The requested action, e.g. restart
  //   $extra:  Any values needed by the backend to perform this action
  commit($action, $extra)

Rule 3 - Variable, object and function names

A) A variable name should either be a single word, for example $address or you should use the underscore character ("_") to make clear what a variable stores.

  // good
    $domain_panel_domain = "hostname.org";
  // bad
    $domainnameusedforpaneldomain = "hostname.org";

Obviously you would use better variable names than those mentioned above but the point is that underscores should be used to clarify variable names, do not use domainname as a variable it is hard to read. This also applies to function names since they must be easy to reference.

B) Never use capitals/uppercase characters in a variable name, why do this, it simply makes it harder to read, its like using uppercase HTML tags alongside lowercase ones!

Rule 4 - Quoting strings

A) Always use single quotes, they prevent the parser from doing extra work on the string. You can use double quotes if they contain variables, but only when they are simple variables. Special characters do not work in single quoted strings, use double quotes. Do not use any form of quotation when there is only a single variable.

    $var = 'Some string'; // good
    $var = “Some string”; // bad
    $var = $var2; // good
    $var = “$var2”; // bad
    $var = “Some string: $var2”; // good
    $var = 'Some string: '.$array[2]; // good
    $var = “Some string: {$array[2]}”; // bad
    $var = “First line \n Second line”; // good
    $var = 'First line \n Second line'; // bad, doesn't work