Coding guidelines

Contents:

General

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)

Some general rules:

• 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).
• Keep a fluid dialog with the others coders, they have their own thoughts about what you are doing.
• Ask if you are in doubt.

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, instead use "Lower CamelCase":

function questionsRetrieve( $iQID, $iSurvey)

• What about files? Unless Yii requires it in some way always name your files in lowercase - this prevents problems on systems using case-aware filesystems

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!.

Localization

Currently we are using the gT(),eT(),ngT() and neT() functions of the limesurvey_lang object for translations.

Since LimeSurvey is available in 60 languages it is very important that your original English string (which will be picked up automatically for translation by our translators) is done right from the start. Imagine if we have to correct only one string at a later time - then 60 strings become invalid across the project and need to be re-translated by the poor translator souls.

• gT() is the original translation function. It will return a translated version of the string in the currently selected language. ie: echo $clang->gT("Hello");
• ngT() returns multiple translations of a sentence or phrase for which alternate plural forms may apply. ie: echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers);
• eT() echos the translation directly. (ie: instead of echo $clang->gT("Hello"); you can use $clang->eT("Hello");
• neT() echos the multiple translations of the sentence or phrase for which alternate plural forms may apply directly.

Please follow these important rules:

• Do not embed margin spaces in your translation. Instead use proper CSS formatting

Wrong: $clang->eT('Visible? ');

Right: $clang->eT('Visible?');

• Do not capitalize words except where grammatically correct (like at the beginning of a sentence or for a brand name). LimeSurvey is not a newspaper.

Wrong: $clang->eT('Create A New Label Set');

Right: $clang->eT('Create a new label set');

Wrong: $clang->eT('Google Maps API Key');

Right: $clang->eT('Google Maps API key');

• Do not concatenate several translations to form a sentence or concatenate to an additional information (like a number or string). Instead use the sprint() or sprintf() function with placeholders.

Wrong: echo $clang->gT('The sum must not be bigger than').$iMaxSum;

Right: echo sprintf($clang->gT('The sum must not be bigger than %s'),$iMaxSum);

This comes from the problem that in other languages the setting of a sentence can be much different and the information $iMaxSum from the example above might be needed in the middle of the sentence.

Wrong: echo $clang->gT('The user').$sUsername.$clang->gT('was deleted.');

Right: echo sprintf($clang->gT('The user %s was deleted.'),$sUsername);

• Use the n*T functions where applicable. These functions show a different translation depending the number of items. Currently LimeSurvey only supports the numbers/situations 1 and >1.

+Example:

Wrong: echo sprintf($clang->gT('Please select at least %s answer(s).'),$iMinimumAnswers);

Right: echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers);

Bug tracker

1. First consider if the reported issue is really a bug. If it is a feature request please point the reporter to http://ideas.limesurvey.org and set the issue status to 'Closed'.
2. If you would like to work on a bug assign it to yourself.
3. Try to reproduce the issue.
   1. If you cannot reproduce ask the user to provide a small example survey to demonstrate the issue. Then set the issue to 'Feedback'. After the user added the necessary information it will automatically be set to 'Assigned' again.
   2. If the user does not responds for more than a week ask once again for feedback by adding a comment. After a further week without feedback close the issue.
4. After you resolved the issue set the status to resolved AND provide the 'Fixed in version' information.
5. After you committed your fix add a comment to the resolved issue 'Fixed in rev. <Subversion revision number>'
6. After a release the release technician will set all issues to 'Closed' that were fixed for this release. That signals to the reporter that a fix is available in the version and it was just released.

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.