[limesurvey-developers] RE : About coding rules (revised)
The leading Open Source survey tool
Brought to you by:
c_schmitz
From: Thibault Le M. <Thi...@su...> - 2007-06-15 09:01:06
|
Hi, > Naming convention > ***************** > =20 > - Use the Hungarian Rule: > Variables: > [a][T]NameOfVariable > | | -------+------ > | | +-------> Descriptive name > | +----------------> Datatype stored > +-------------------> Start with "a" it is an array > =20 > Examples: > aQuestions: Array where store the questions attributes > dSurveyEnds: Date when the survey void Is it [a][T] or [a]|[T] ? =3D=3D> What should be the name of an array of strings: aMyString or = asMyString ? > - In case a function is declared, it will honnors the same=20 > rule: function aQuestionsRetrieve( iqid, isurvey) // it will=20 > return an array=20 Same remark as above. =20 > Documentation > ************* >=20 > - Functions must have an explanation about what process,=20 > returns, etc... We should define a header structure... Does someone has skills with phpdocumentor (http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutoria= l_p hpDocumentor.quickstart.pkg.html#coding) or similar things ? >=20 > - Allways a process or conditional structure must have an=20 > remark about its close statament: > // Processing each condition retrieved > foreach ($cd in $conditions) > { > ... > } // ends foreach ($cd in $conditions) Agree ;-) > Structures > ******************* >=20 > - Indent using spaces instead TAB, or be gentle to announce=20 > how many spaces are your TABs long I disagree... We MUST decide whether to use Tabs OR Spaces otherwise the code becomes very ugly from on editor to another. I prefer tabs because it's easy then to let anyone choose the tab length = to suit its editor width (that's why I often changes space indents to tabs = in the code when possible). However if we decide to use spaces, we MUST explicitely impose the number of spaces used for a single ident. > - The opening curly braces must be bellow the sctructure opening: > if (condition) > { > ... > } I Agree, though it wasn't my coding style at first, I now really = appreciate this. > - Using one line for a simple condition is very "fashion" a=20 > taste of "hacker", but it is not clear at all: > BAD: if (condition) {do true} else {do false} > BAD: if (condition) {do true}=20 > else {do false} > GOOD: if (condition) > { > do true > } else > { > do false > } I agree but sometimes the code may become 'over idented' and using = tricks like this may make the code more readable in some specific cases... > - SQL sentences must honnors the same rule and MUST BE ENDED=20 > with the ';': > $sSQL =3D "SELECT field1, " > . "field2, " > . "field3 " > . "WHERE condition " > . "AND condition " > . "OR condition " > . "ORDER BY field1, " > . "field2;" Ok. > - The same for HTML tags: > PRINT >>> END > <table width=3D'99%'=20 > align=3D'center'=20 > style=3D'margin: 3px 6px;=20 > border: 1px solid #555555'=20 > cellpadding=3D'1'=20 > cellspacing=3D'0'/> >=20 > <tr/> > <td colspan=3D'2'=20 > height=3D'4'/> > <strong/> > Some Text > </strong/> > </td/> > </tr/> > </table/> > <<< END !!!!!! I realy thought <table ..../> was equivalent to <table = ...></table> AFAIK in XHTML you have to close elements with no contents such as <br/> = but your table can't start with <table .../> and end with </table/> > - If using an auxiliar variable makes clear the code or=20 > process, just do it. ??? Can you be more specific I don't catch this |