|
||||||
|
Relate Components | RelateScript | BlueStep.js |
Style Guidelines
Following proper style guidelines can make the meaning of a formula much clearer to a human reader. Conversely, using poor style can make a piece of formula logic difficult to read, even for experienced software developers. Style guidelines do not affect the logic or outcome of a formula, but if followed they can make scripts easier to read, easier to maintain and (with a bit of experience) help to identify problems. Also, although these guidelines cover many cases, there will always be cases that don't fit the guidelines and will need improvisation. The goal is always the same though: style techniques should make the meaning of the logic clearer. Indentifiers At the same time, avoid using names that are so long that they are cumbersome to type. Excessively long names can also cause trouble by taking up so much room on a line that other parts of the line cannot be seen in the formula edit window. This obscures the meaning of the formula rather than making it clearer. The most important rule in naming things is this warning: If there are two fields or variables which do similar things be SURE that the names chosen clearly indicate which name is used for what. There are few things that make a piece of logic more difficult to read than two variables with similar names and no clear indication of what the difference is. Lastly, the use of "camel case" is recommended. Since identifier names cannot contain spaces, it can become difficult to distinguish word boundaries. One such example is a domain which BlueStep purchased and later regretted. It was "answers4therapists.com". Is that 'answers for therapists' or 'answers for the rapists'? Camel caps solves this problem by capitalizing the first letter of each word after the first word. So, in our example it should be answers4Therapists.com not answers4TheRapists.com. With a little practice, oneCanLearnToReadCamelCapsQuiteEasily. Any words which are acronyms should be all caps (or all lowercase, if they are the first word) as in: mySpecialURL Whitespace Put a space before and after most mathematical operators. In writing x=y+z it's not that much more readable as x = y + z, but as the complexity of the logic grows, so does the need for spaces. Consider the following fragment from an actual script: Guidelines for other symbols include: put a space after, but not before, commas and semi-colons. Do not put a space between a prefix or suffix operator and the thing it is operating on: y * -x, Normally, a space is put before an opening parenthesis (but not after), and after a closing parenthesis (but not before.) However, with nested paretheses there should be no space between adjacent parentheses. For example: There should not be spaces around a period or around square brackets, unless another rule would require it. myArray[5] = someForm.someField Following an opening brace (that's the curly kind), begin a new line and indent each line after the brace until reaching the matching closing brace. The closing brace should begin a new line and be indented the same amount as the line containing the opening brace. Here is an example: In a very long line, it is helpful to break it into multiple lines. Double indent (or more) each line that was originally part the first line. Also, it is helpful to begin each new line with an operator to clearly indicate that this line belongs with the previous one: Comments Summary |