Coding guidelines
From LimeSurvey Manual
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? 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 gT,eT,ngT and neT function of the limesurvey_lang object for translations. LimeSurvey is available in 60 languages so it is most important that your English original string (which will be picked up automatically by the translators) is done right from the start. Because if we have to correct a string at a later time then 60 strings become invalid across the project and need to be re-translated.
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 concatinate several translations to form a sentence or concatinate 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 then 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);
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!