Revision 374191 of Basic code style guidelines for Robocop tests

  • Revision slug: Mozilla/QA/Robocop/Code_style_guidelines
  • Revision title: Basic code style guidelines for Robocop tests
  • Revision id: 374191
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment finished editorial review and copyeditBasic_Code_Styling_Guidelines_for_Robocop_tests Mozilla/QA/Robocop/Code_style_guidelines

Revision Content

This page provides a set of minimum guidelines for code formatting and coding style that you need to follow in order to get a positive review on a patch when creating Robocop tests. It's worth noting that these guidelines are similar or the same the standard Firefox coding style, so if you're familiar with those, you're in great shape.

Basic code guidelines

These gudelines must be followed.

  • All tab characters should be replaced by 4 spaces - use the "use spaces" option in your editor to substitute tab with spaces. This differs from standard Firefox style guidelines, which specify 2 spaces per tab.
  • No spaces should be present at the end of a line after ";", "}", "{" or any other line ending character.
  • Comments should be added to the code to explain what the code does every time you think you might need to explain what or why you did things like that.
  • One-line comments should use "//". There should always be a space after "//" and the first letter of the comment should be capitalized, as below:
// This is a one line comment
  • Multiple line comments should use the format " /* comment */ ". The same rules of the single line comment apply, plus the text should be aligned for the different lines of the comment:
/* This is a multiple line comment
   The text should be aligned at the first letter not the comment start */
  • Long comments should be spread across multiple lines instead of leaving them to be handled by display formatting in the editor.
  • Blank lines can be used inside the body of a method and should be used only to separate logically connected blocks of code.
  • After each "{", the text should be indented with an additional tab which should be eliminated at the first "}", as demonstrated below:
first_lvl_of_indentation {
    second_lvl_of_indentation {
        3rd_lvl_of_indentation {
        }
    }
    We are now at the second level
}

We are back at the 1st level of indentation
  • Correct spacing should be used when writing methods. For example:
method_name(arg1, arg2, arg3) {

Note that there's no space between the method name and the opening parenthesis for the parameter list, there are spaces after each "," in the parameter list, and there's and a space closing parenthesis at the end of the list and the "{".

  • Leave a blank line between the end of one method and the beginning of the next.
  • Do not leave a blank line between the end of the last method in the class and the end of the class.
class {
    variables defined here

    method1() {
    }

    method2() {
    }

    method3() {
    }
}
  • Do not leave a blank line between the class declaration and the global variable declaration blocks; also, indent the variable declaration block to the first method declaration.
  • When testing equality between two strings, use  the String class's equals() instead of the == operator. For example:
String1.equals(String2);
  • If a block of code is used more then twice in a class, turn it into a method.
  • If a method needs to change the value of a parameter it receives, but you don't want to change it globally, you need to define the parameter using an "m" before the label:
class example {
    int globalVariable;
    ...
    method(int mGlobalVariable) {
    int globalVariable = mGlobalVariable;
    ....
    }
}
  • When naming methods and variables, use descriptive names.
  • Use camel case for variable names (the name starts with a non-capital letter, the words making up the name are not separated and each following word is capitalized). For example, thisIsAVariableNameWrittenInCamelCase.
  • If a method used in your test would be useful in further/other tests define it in BaseTest or PixelTest, not in your test class. This is not a requirement for positive review, but failure to do so will usually result in a follow-up bug after patch acceptance.
  • Make variables and methods which do not need to be accessed from outside the class private.
  • Declare variables that do not change final.
  • Do not hardcode any data. If you need a value somewhere, declare it as a variable at the beginning of the code. These might be URLs, timeout values, or the like. Having these values all in variables at the beginning of your code makes it easier to find and change them later if necessary.
  • When using timeouts for your test, reuse the ones declared in BaseTest unless you need different values for the timeout.
  • Clean up the import list after you've finished writing and testing your test by removing any imports that are not used in the final version of the test.
  • Remove any variables that you end up not using in the test.
  • If you have multiple variables that are of the same type and logically connected, add them in an array rather then declaing them separately. For example, this would apply to a list of options.

Revision Source

<p id="General_Info">This page provides a set of minimum guidelines for <strong>code formatting</strong> and <strong>coding style</strong> that you need to follow in order to get a positive review on a patch when creating Robocop tests. It's worth noting that these guidelines are similar or the same the standard Firefox <a href="/en-US/docs/Developer_Guide/Coding_Style" title="/en-US/docs/Developer_Guide/Coding_Style">coding style</a>, so if you're familiar with those, you're in great shape.</p>
<h2>Basic code guidelines</h2>
<p>These gudelines must be followed.</p>
<ul>
  <li>All tab characters should be replaced by 4 spaces - use the "use spaces" option in your editor to substitute tab with spaces. <strong>This differs from standard Firefox style guidelines, which specify 2 spaces per tab</strong>.</li>
  <li>No spaces should be present at the end of a line after ";", "}", "{" or any other line ending character.</li>
  <li>Comments should be added to the code to explain what the code does every time you think you might need to explain what or why you did things like that.</li>
  <li>One-line comments should use "//". There should always be a space after "//" and the first letter of the comment should be capitalized, as below:</li>
</ul>
<pre>
// This is a one line comment
</pre>
<ul>
  <li>Multiple line comments should use the format " /* comment */ ". The same rules of the single line comment apply, plus the text should be aligned for the different lines of the comment:</li>
</ul>
<pre>
/* This is a multiple line comment
   The text should be aligned at the first letter not the comment start */
</pre>
<ul>
  <li>Long comments should be spread across multiple lines instead of leaving them to be handled by display formatting in the editor.</li>
  <li>Blank lines can be used inside the body of a method and should be used only to separate logically connected blocks of code.</li>
  <li>After each "{", the text should be indented with an additional tab which should be eliminated at the first "}", as demonstrated below:</li>
</ul>
<pre>
first_lvl_of_indentation {
    second_lvl_of_indentation {
        3rd_lvl_of_indentation {
        }
    }
    We are now at the second level
}

We are back at the 1st level of indentation</pre>
<ul>
  <li>Correct spacing should be used when writing methods. For example:</li>
</ul>
<pre>
method_name(arg1, arg2, arg3) {
</pre>
<p>Note that there's no space between the method name and the opening parenthesis for the parameter list, there are spaces after each "," in the parameter list, and there's and a space closing parenthesis at the end of the list and the "{".</p>
<ul>
  <li>Leave a blank line between the end of one method and the beginning of the next.</li>
  <li>Do not leave a blank line between the end of the last method in the class and the end of the class.</li>
</ul>
<pre>
class {
    variables defined here

    method1() {
    }

    method2() {
    }

    method3() {
    }
}
</pre>
<ul>
  <li>Do not leave a blank line between the class declaration and the global variable declaration blocks; also, indent the variable declaration block to the first method declaration.</li>
  <li>When testing equality between two strings, use&nbsp; the String class's <code>equals()</code> instead of the <code>==</code> operator. For example:</li>
</ul>
<pre>
String1.equals(String2);
</pre>
<ul>
  <li>If a block of code is used more then twice in a class, turn it into a method.</li>
  <li>If a method needs to change the value of a parameter it receives, but you don't want to change it globally, you need to define the parameter using an "m" before the label:</li>
</ul>
<pre>
class example {
    int globalVariable;
    ...
    method(int mGlobalVariable) {
    int globalVariable = mGlobalVariable;
    ....
    }
}
</pre>
<ul>
  <li>When naming methods and variables, use descriptive names.</li>
  <li>Use camel case for variable names (the name starts with a non-capital letter, the words making up the name are not separated and each following word is capitalized). For example, <code>thisIsAVariableNameWrittenInCamelCase</code>.</li>
  <li>If a method used in your test would be useful in further/other tests define it in <code>BaseTest</code> or <code>PixelTest</code>, not in your test class. <b>This is not a requirement for positive review, but failure to do so will usually result in a follow-up bug after patch acceptance</b>.</li>
  <li>Make variables and methods which do not need to be accessed from outside the class <code>private</code>.</li>
  <li>Declare variables that do not change <code>final</code>.</li>
  <li>Do not hardcode any data. If you need a value somewhere, declare it as a variable at the beginning of the code. These might be URLs, timeout values, or the like. Having these values all in variables at the beginning of your code makes it easier to find and change them later if necessary.</li>
  <li>When using timeouts for your test, reuse the ones declared in <code>BaseTest</code> unless you need different values for the timeout.</li>
  <li>Clean up the import list after you've finished writing and testing your test by removing any imports that are not used in the final version of the test.</li>
  <li>Remove any variables that you end up not using in the test.</li>
  <li>If you have multiple variables that are of the same type and logically connected, add them in an array rather then declaing them separately. For example, this would apply to a list of options.</li>
</ul>
Revert to this revision