Coding Guidelines

Hello dear friends of Admidio!

This document should help to generate clean code, comprehensible to other people. The points listed here are merely to be understood as implementation proposals. If in doubt, you should just turn your mind and think about whether this is all really so clear, as has been imagined.

You should exercise some discipline during programming. This includes the avoidance of German umlauts characters, unified Code spacing and much more. It applies to all programming languages that are used in Admidio (PHP, JavaScript).

This document is mainly directed at developers who want to install their code like in the official Admidio release, but also for the private development these guidelines can be helpful. The document is actually not finished yet. Who like to add own chapter or comments is welcome.

Indents are most important to keep your code structured.

We opted for indentation of four spaces. In the development environment a tab must be set equivalent to four spaces. In addition, everyone should specify that the tabs are replaced with spaces when pasting / saving. The indent then applies for both PHP, JavaScript and HTML code.

echo '
<table>
    <tr>
        <td>Only a test</td>
    </tr>
</table>';

With control structures following elements are meant:

• if
• for
• while
• switch

The open parenthesis is set after the control structure with a space between. The closing parenthesis is always set at the height of the control structure.

Here is an example of a nested if statement:

if ((condition1) && (condition2)) {
    action1;
    if (condition3) {
        action2;
    }
} elseif ((condition4) or (condition5)) {
    action3;
    action4;
} else {
    defaultaction;
}

Here is the explanation:

• Those who want to can make 1 space between Control keyword (IF) and the condition in order to distinguish them from method calls. However, this is up to you.
• even if only one action is defined always use braces

Here is an example of a switch / case statement:

switch (condition) {
    case 1:
        action1;
        break;
 
    case 2:
        action2;
        break;
 
    default:
        defaultaction;
        break;
}

Shortened spellings, such as the following If statement should be avoided for reasons of clarity!

(condition) ? action1 : action2

A function call always happens with no spaces between the function name, the opening parenthesis and the first transfer parameter. The individual parameters are separated with commas and spaces separated from each other. Behind the last parameter no more space is used. Below is another example:

$var = function($para1, $para2, $para3);

As shown above, on the left and right side of the equal sign where is one blank respectively. If several function calls and thus variable assignments in the block are under each other, in order to ensure the readability of the code, you may deviate from it:

$test        = foo($para1);
$longerName = foo($para2);

When defining functions, the arguments are set to the end of the declaration with default values. Function names, arguments and return values should be self-explanatory. Here's an example:

function addition($value1, $value2, $value3 = 0)
{
    $result = $value1 + $value2 + $value3;
 
    return $result;
}

So that others can fix in your code that may have bugs, this must not only be clear, but also understandable. Therefore, one or the other comment is inevitable. Here, the right balance has to be chosen. Too much comment distract the view on the essentials (the Code), less comments makes it appear impenetrable …

Comments should be generally recognized in English, so that the source code can be read by non-German developers. In the documentation of classes, methods and functions we use Doxygen. This allows to create a clear HTML Help. However, comments must be set within a few tags. Therefor a Description of documentation with Doxygen is available.

Comments directly in the source code (no function and method description) must be indented, so that they are on the same level as the commenting construct. One- to two-line comments are shown as follows:

// This is the first line of a short comment
// This is the second line of a short comment

As shown above, German umlaut characters should also be avoided in comments. Extends a comment more than 2 lines a block should be used for comments:

/* This comment could be very long ...
* This comment could be very long ...
* This comment could be very long ...
* This comment could be very very very long ...  */

Important in blog comments are the * at the beginning of the line. These are not necessary, but improves the overview considerably and should therefore be set.

You should put your PHP code within the tags <?php and ?> and not use the short form <? ?> . This is the only way to ensure that the code is interpreted across all platforms well as PHP code.

Each file of Admidio project should have a documentation block at the beginning of the file.This block must have an short explanation of PHP the script. In addition, all possible parmeters that may be passed from other scripts are here to neatly listed … Here is an example from the file dates_function.php:

/**
 ***********************************************************************************************
 * Set the correct startpage for Admidio
 *
 * @copyright 2004-2015 The Admidio Team
 * @see http://www.admidio.org/
 * @license https://www.gnu.org/licenses/gpl-2.0.html GNU General Public License v2.0 only
 *
 * Uebergaben:
 *
 * dat_id: ID of the event to be shown
 * mode:   1 - New/Change event
 *         2 - Delete event
 *         4 - Export to i-cal
 *         5 - Notice to delete an event
 ***********************************************************************************************
 */
 

When files are checked into Git, a commit message must be drawn up. In a bugfix the commit message definitely should belong to the associated issue number e.g. #123 and a short description of the activities done in the script …

Classes
Classes are to be defined with self-explanatory name. Cryptic abbreviations should be avoided if possible. Classes should always start with a capital letter.

Functions
Function names should be written in camel style (many also known as camelCaps or laOlaStyle). This is meant the first letter is written lowercase and the first letter of the next word in Capital letter.
Example:

getSystemData();

Variables
Variables should be similar to the function name written in camel style (many also known as camelCaps or laOlaStyle). Global variables are system-wide get a g prefix, passed variables get in a script a get or post as a prefix so that always is directly clear that the content of variables can be manipulated.
Example:

numberRows  // Description of the variable
gCurrentUser  // global variable
getUserId  // passed variable to a script

Constants
For constants all letters are capitalized and separated in individual words within the name by underscores.
Example:

TBL_ORGANIZATIONS

To guarantee the development of various systems, a standard format must be used:

• Charset UTF-8
• Newline LF

If you checkout the code with GIT you could configure if you want it in LF (Linux) or CRLF (Windows).

In UTF-8 is still too aware that the Editor the byte order flag (BOM) must not set. This flag is actually establishing the exact identity of the UTF used encoding (UTF-8, UTF-16 or UTF-32). If using this in PHP, it will simply output the script at the beginning in the browser and then it mostly leads to an error message in the script.

• Filenames of scripts must always be written in lower case, as some servers are still configured so that they do not get along with the upper case.
• If a script name is named with multiple words, they should be separated by an underscore _
  Example: new_user_function.php
• The main script of a module should be called exactly as the module folder
  Example: adm_program/modules/anouncements/announcements.php

All strings are enclosed in single quotes. Example:

$array['element'] = $object->getValue('id');
$string = 'example';

Arguments within strings are enclosed in double quotes. Example:

echo '<img src="image1.jpg" alt="Image" />';
$sql = 'SELECT * FROM '. TBL_TEXT. ' WHERE txt_value = "example" ';

Within JavaScript, however, the double quotation marks should be used, so that as less as possible characters need to be escaped. This JavaScript code can be copied easily between the scripts, we should take the double quotes even in pure JavaScript files.

echo '<script type="text/javascript"><!--
               var string = "double quotation marks";
               var array["element"];
--></script>';

Exceptions to these rules is JavaScript code directly in HTML attributes. There, the single quotes (escaped) must be taken, otherwise the attribute is terminated.

echo '<a href="javascript: example(\'passed\');" target="_self">Html-Code</a>';

When comparing the contents of variables, the operators should be chosen so that even the type (integer / string) is checked in one step. This is achieved by is equal with === or unequal with !==.

if($a == $b)  // only checks whether the content is the same. "Test" == Test   > true
if($a === $b) // checks whether the type is the same. "Test" === Test   > false
              //                                   "Test" === "Test" > true
 
if($a != $b)  // only checks whether the content is unequal. "Test" != Test2   > true
if($a !== $b) // checks whether the type is not equal. "Test" !== Test   > false
              //                                   "Test2" !== "Test" > true