RNTeam:Coding Standards

Process>Coding Standards

These pages are not meant to be taken by the general public as "end-all" static statements of direction. They are more "guiding principles" and they can and will change over time. We make these available here so the RavenNuke Team has one place to go to for this type of information, when decisions on direction have been made, and we decided to give the "public" a "peek" into what we are trying to accomplish... a "process roadmap" if you will.

NOTE: These standards do NOT apply to code that is incorporated into RavenNuke unless the designated maintainer desires to re-code (including updates) OR the code being incorporated is no longer being supported by the author. In the latter case, the code becomes "core" to RavenNuke, therefore, it should be upgraded to Standard wherever possible.

You will note that we intend for this to be light-hearted! How else are we to have fun with "standards". :-)

Indenting and Line Length

Tabs shall be used instead of spaces for the following reasons:

1. Although traditionally an issue with CVS (according to PEAR), does not seem to affect Subversion.
2. Too easy to forget to set desired standard tab stops in editors which replace spaces for tabs, which end up causing our indentation to be inconsistent (sometimes 2 spaces, other times 3 or 4 or __).
3. In some editors used by the Team (such as NuSphere PhpED), spaces are more difficult to "ignore" for indentation purposes.
4. Because this is what Raven has asked us to do - LOL.

Just use good judgment in terms of line lengths. Remember that having to look through unwrapped (and even auto-wrapped code) can be VERY difficult to digest. Most of us now use better text editors or IDE's and have much larger screens that the "old days", so we can go a little longer, but, again, use good judgment. (And if you are reading this and you are really h___ bent on using command line vi editor... tough!)

String Parsing vs. Concatenation

This one is a performance play. String concatenation is faster than string parsing. (Some PHP experts are saying that this has been greatly eliminated in PHP5.2, but why even mess with "greatly"... we've noticed the difference and so have our customers.) So, wherever possible, use something like this:

$sql = 'SELECT * FROM `' . $prefix . '_users` WHERE `user_id` = \'' . $id . '\'';

as apposed to this:

$sql = "SELECT * FROM `$prefix_users` WHERE `user_id` = '$id'";

See that the first example is nicely formatted with spaces in-between the "dot" concatenation operator and with spaces around the "=" signs. It just helps with readability when trying to debug a long concatenated string.

Here is another nice tid-bit from Gremmie regarding string concatenation while using echo. Do this:

echo 'I am a long string var with ', $somevar, ' inserted in the middle.', $canhaveasmanyasyouwant, ...;

Instead of:

echo 'I am a long string var with ' . $somevar . ' inserted in the middle.' . $canhaveasmanyasyouwant . ...;

This is faster as echo actually takes any number of arguments. Much better to take advantage of a PHP construct than to use a function (i.e., concatenation).

As with everything, though, there are trade-offs. The real key here is that if something just makes better sense to use, such as the very slow HEREDOC syntax for large blocks of HTML with lots of variable replacements, use the tool that fits the job! HEREDOC syntax should be used for including inline HTML instead of breaking out of PHP every time. Echo's are sufficient for the smaller HTML code/fragments, but if you have a block of HTML code HEREDOC is much less cumbersome and more easily maintained thank an ugly string of code, quotes, tick marks, etc.

Related Assignment "Blocking"

In most cases, there should be only one space before and after the equal sign ("=") in an assignment. Some would argue that with blocks of related assignments, that the following might be desired:

$short         = foo($bar);
$long_variable = foo($baz);

This can cause issues when one wants to perform a global search and replace of a variable name (unless the substituted variable is of exactly the same length). There really is no need to have the extra spaces and it is slightly less script file size and parsing. However, please, NEVER use tabs for formatting code outside of just left-hand indentation!

Control Structures

Sticky subject for most. The key is not to get so entangled in "it has to be this way" that we don't want to write "tight" or "elegant" code. Again, a judgment call as to whether to use more "short-hand" code; others can stand to learn how to write more elegant code - wink - if there is a legitimate purpose, such as performance.

Here are some sample control structures, taken in their most complicated form, to give you an idea of what we're after (control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls).

IF-THEN-ELSE/ELSEIF

if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}

The "default" condition should be placed at the top of the "SWITCH" structure.

SWITCH

switch (condition) {
default:
    defaultaction;
    break;

case 1:
    action1;
    break;

case 2:
    action2;
    break;
}

All other control structures should follow suit.

Function Calls

Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here's an example:

$var = foo($bar, $baz, $quux);

Function Definitions

It is pretty much an accepted "standard" that arguments with default values should go at the end of the function argument list. This is possibly a carry over from JavaScript requiring it, at least in some earlier versions. It is also somewhat more aesthetic to the eye not having to process back-and-forth switching from non-defaulted values to defaulted ones. So, we should accept this as a standard. It is a good idea to always give consideration to providing default values as an added security measure - i.e., you can count on the value if one is not provided. It would also be good to give consideration to passing variables by reference. There is a trade-off here, though, yes, we get increased performance and decreased RAM profile, but now one has to be EXTRA careful modifying values!

function connect(&$dsn, $persistent = false) {
    //... code goes here
}

NOTE: Objects in PHP5 are always passed by reference (this was not so in PHP4).

Another consideration with functions is to try and return a meaningful value if one is appropriate. Again, trying to ensure good control over both inputs and outputs of the function and ensure consistency for their "constituents".

Class Definitions

Not really all that different from Function Definitions...

class Foo_Bar {
    //... code goes here
}

Comments

Code documenting standards will be developed elsewhere, but just a quick note about commenting style. Because many text/code editors do not properly highlight PHP syntax when the Perl/Shell script type comment of "#" is used, and will actually cause the editor a migraine and throw off all code coloring from that point on, we will only use C/C++ style comments. So, like these:

/* Nice comments */
// Nice comments
/**
 * Even nicer comments if we're going to use PHPDocumentor
 */
# Not so nice... everything below here gets all syntax hosed up.  :-(

Including Code

This is another interesting one. It is actually claimed (and proven) that on very busy sites that only include/require should be used (see http://pear.php.net/manual/en/pear2cs.php). However, we prefer the extra security (and silly?) aspect of using include_once and require_once. It may also be a lesser known fact that these are not functions! Therefore, the following are better examples of usage:

include_once 'header.php';
require_once 'mainfile.php';
require_once INCLUDE_PATH . 'custom_files/custom_head.php';

Yes, this is faster... don't ask me why because I didn't feel like debating the author. Took 'em at their word.

PHP Code Tags

It is preferred to use <?php ?> instead of <? ?> for portability purposes.

Naming Conventions

This can really get controversial, so I'll leave it to the "big guns" to decide if and when such conventions are determined.

However (yes, there always is one), there is already a convention used within *nuke (thank God there is at least ONE!) where constants are all in UPPER_CASE_WITH_INDIVIDUAL_NODES_SEPARATED_LIKE_THIS. So, might as well stick with that convention... I know, they place an extra underscore at the beginning, but personally, who cares? The key is all CAPS which makes it very clear as to what it is.

At some point it might make sense to include some conventions especially when we get heavier into classes. It would be nice to adopt common conventions that many OO programmers are already familiar with.

File Formats

This could change at some point especially if we consider UTF-8 support. For now, since we pretty much all develop using XAMPP in a Windows environment with Windows based GUI type tools, we store files in ASCII text with standard ISO-8859-1 character encoding. Again, at some point, this might have to change?

VERY IMPORTANT NOTE: We have had numerous issues reported over the years (mostly end-user caused by using bad text editors) with extra lines following the closing ?> line. I have actually heard two different solutions to this: 1) well, don't add the extra line - lol, and 2) don't include the closing ?> tag. We know that 1) works every time, but 2) might be a consideration, but have never tried it within this CMS, so might want to get confirmation before we go making a standard out of it.

Error Reporting Levels

We have made tremendous strides to clear up any and all PHP Warnings within the code. But, as we muck around with files (language files can be the killers), we must always, always, always make sure that we test with $display_errors = true within config.php and with $error_reporting = E_ALL within rnconfig.php as a minimum. We might also want to consider E_ALL | E_STRICT, but, unfortunately, that means having to do more clean-up... and on date related functions. Uuggh. LOL.

Error Handling Guidelines

We might be able to incorporate a couple of things here, such as also testing with the $loglevel = 1; within rnconfig.php set. But, ideally, we'd be working with an error handling class within PHP5 with more complete and robust capabilities (try/catch anyone?). Some day.

Stop the Insanity

<MONTEGO_RANT>

I have saved the best for last. Have you ever seen this within PHP-Nuke?

$somevar = "$anothervar";

We need to really stop this insanity as it holds NO value, security or otherwise, and is exactly equivalent to simple this:

$somevar = $anothervar;

Aaaaarrrggghhh... ok. Feel better now...

</MONTEGO_RANT>

<RAVEN_RANT>

Or, this one:

$somevar = "".SOME_CONSTANT."";

Should simply be:

$somevar = SOME_CONSTANT;

</RAVEN_RANT>

And, yes, these sub-headings do look very much like the ones from the PEAR Coding Standards... ;-) We have a base now to discuss and get a final agreement upon.