Coding guidelines

Contents:

Naming convention

• Use the Hungarian Rule for variables:

[t]NameOfVariable

 | <strike>-</strike><strike>+</strike>----

 |        +--> Descriptive name

 +--> Datatype stored (for example start with "a" if it is an array)

Examples:

aQuestionAttributes: Array to store the questions attributes, Mixed values

dSurveyEnds: Date when the survey ends

sContditionsOutput: String used to create the JS for conditions

• In case a function is declared do not use the Hungarian rule for the function name, only for the variables:

function questionsRetrieve( $iQID, $iSurvey)

• What about files? Try to name the file as close to its contents as possible:

+admin.php: functions or routines related to admin interface

+html.php: functions or routines related to HTML generation

Documentation

Please refer to this introduction: How to document your source code.

Structures

• Indent using spaces instead of TAB, or be gentle to announce how many spaces are your TABs long. There is wide ranging debate about tabs vs. spaces, many people prefer using tabs, others prefer spaces, others are happy with a mix of tabs and spaces. Because LimeSurvey is developed collaboratively, we ask that you leave your preference and follow this standard.
• The opening curly brace must be below the structure opening:

if (condition)

{

   ...

}

• Using one line for a simple condition is very "fashionable", a taste of "hacker", but it is not clear at all:

 WRONG: if (condition) {do true} else {do false}

 WRONG: if (condition) {do true}

        else {do false}

 RIGHT: if (condition)

        {

           do true

        } else

        {

           do false

        }

 RIGHT: swith $sSelector

        {

              case X:

                   ...

                   break;

              case Y:

                   ...

              default:

        }

NOTE: It´s true that sometimes the "WRONG" way can be useful, but if it makes the straight reading difficult, please use the "RIGHT" way instead. Be gentle with your fellow developers.

• SQL sentences must respect the same rule:

 $sSQL = "SELECT field1, field2, field3 "

        ."WHERE condition "

        ."AND condition "

        ."OR condition "

        ."ORDER BY field1, field2";

• The same for HTML in views tags:

<table>

<tr>

 <td colspan='2'

     height='4'>

  <strong>

   Some Text

  </strong>

 </td>

</tr>

</table>

HTML

• As you will notice, a very customized HTML element can take a lot of lines (very expensive if you paid each one (:wink:) ) to avoid that, use 'CSS classes'. In general, use classes to aesthetic related stuff: color, borders, backgrounds, font faces, sizes, etc.
• Respect W3C standards, and try to use the HTML understandable for all browsers. If one of them has a special feature, think if this feature is so special to break down the HTML in other browsers.
• Do not use PHP short tags <? ?>. Always use full PHP tags <?php ?>
• Any rules of the mentioned before: about CSS, well closed HTML tags and JS respect XHTML standards. Give it a try!.

Miscellaneous

• Do not use "global" to access to a declared variable in another process. Pass variables or arrays by reference, use the session or the configuration object.
• If using an auxiliary variable makes clear the code or process, just do it. If you are coding a very complex expression, calling to functions with parameters that are other functions:

WRONG:

iAResult= fa(fb(p1,p2),fc(fd(p3),p4),p5)

It will be more readable:

iAuxB = fb(p1,p2)

iAuxD = fd(p3)

iAuxC = fc(iAuxD,p4)

iAResult = fa(iAuxB, iAuxC, p5)

Anyway, if you are in doubt about someone missing the point or you are afraid that your expression is obscure, take the chance of writing it in a more simple way, even if that involves the use of one or more auxiliary variables.

• Be efficient and save resources (memory and runtime). Things might work for a small survey but also try out your new feature with a survey that has 400 question, 5 languages and 20,000 responses (Yes, there are surveys like this out there).
• There is always a way to write a line avoiding to reach the 80th column. Think of the people who have a 14" CRT (:wink:)
• Keep a fluid dialog with the others coders, they have their own thoughts about what you are doing.
• Ask if you are in doubt.

IMPORTANT

This is a free development, everything you do can be useful for others. If the feature is very personal there is a way to turn it into a universal solution. This is the challenge!

"The difficulty within a solution is to solve it in a simple way" (Lance Burton, magician)