... | ... | @@ -154,20 +154,14 @@ comment. |
|
|
|
|
|
\#\# Method or attributes comments that fit one line should be one line,
|
|
|
i.e., do not do:
|
|
|
|
|
|
|
|
|
```java">
|
|
|
|
|
|
/**
|
|
|
* blah.
|
|
|
*/
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
but:
|
|
|
|
|
|
<code class="java">/** blah. */
|
|
|
```
|
|
|
|
|
|
\#\# in comments always use {@link classname} when referencing a class
|
|
|
|
... | ... | @@ -194,22 +188,16 @@ from each plugin |
|
|
\#\# no magic constants are used, e.g.:
|
|
|
|
|
|
<code class="java">int i = 43 * x
|
|
|
```
|
|
|
|
|
|
|
|
|
->what does 43 mean? use instead:
|
|
|
|
|
|
<code class="java">
|
|
|
final int multiplication_factor = 43;
|
|
|
int i = multiplication_factor * x;
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
similar:
|
|
|
|
|
|
<code class="java">return -2
|
|
|
```
|
|
|
|
|
|
\#\# warning may not be suppressed. only the following two exceptions
|
|
|
apply:
|
... | ... | @@ -265,24 +253,26 @@ the following can be explicitly mentioned during the code review by |
|
|
adding “todo (nn,cxx)” in the code.
|
|
|
|
|
|
1. code having the form:
|
|
|
|
|
|
<code class="java">
|
|
|
if condition {
|
|
|
return true;
|
|
|
} else {
|
|
|
return false;
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
can/should be written:
|
|
|
|
|
|
|
|
|
can/should be written:
|
|
|
|
|
|
<code class="java">return condition;
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
(intermediate expressions might have to be introduced for the
|
|
|
(intermediate expressions might have to be introduced for the
|
|
|
condition, for readability)
|
|
|
|
|
|
2. code having the form:
|
|
|
|
|
|
<code class="java">
|
|
|
if condition {
|
|
|
x = true;
|
... | ... | @@ -290,31 +280,35 @@ adding “todo (nn,cxx)” in the code. |
|
|
x = false;
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
can/should be written:
|
|
|
can/should be written:
|
|
|
|
|
|
<code class="java">x = condition;
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
(intermediate expressions might have to be introduced for the
|
|
|
(intermediate expressions might have to be introduced for the
|
|
|
condition, for readability)
|
|
|
|
|
|
3. code of the form:
|
|
|
|
|
|
<code class="java">
|
|
|
if (x < m ) {
|
|
|
x = m ;
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
should be written:
|
|
|
should be written:
|
|
|
|
|
|
<code class="javax = max(x, m);
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
(`max` is the available in the libray `java.lang.Math`)
|
|
|
(`max` is the available in the libray `java.lang.Math`)
|
|
|
|
|
|
Selectively disable code formatting
|
|
|
===================================
|
... | ... | @@ -331,72 +325,4 @@ forget to turn the Code-Formatter on again, i.e. do not switch the |
|
|
Code-Formatter off and never on again, as this could produce side
|
|
|
effects for other developers.
|
|
|
|
|
|
ATTIC
|
|
|
=====
|
|
|
|
|
|
Original code guideline list
|
|
|
Check-list:
|
|
|
|
|
|
1. No unused (commented out) code
|
|
|
2. No FIXME (indicate known bugs) or TODO without issue reference
|
|
|
3. Every method must be commented (but `param/`return do not have to be
|
|
|
used systematically)
|
|
|
4. Comments for classes, attributes and methods start with a capital
|
|
|
letter and finish with a dot
|
|
|
5. Comments and methods do not contain any spelling mistake (Eclipse
|
|
|
helps for comments)
|
|
|
6. No Eclipse warning
|
|
|
7. `param/`return should be used consistently: either not at all, or
|
|
|
every parameter should have a corresponding `param and `return
|
|
|
should never have an empty comment (but
|
|
|
`param _can have_ some empty comment)
|
|
|
# No empty comment (i.e., no comment without a content)
|
|
|
# The code can be easily understood (names are meaningful and homogeneous, no use of synonyms).
|
|
|
If anything is suspect, take a closer look, ask the author
|
|
|
# The code is meaningfully commented (better no comment at all than a useless one), e.g., "Declaration of variable x." is not a meaningful comment
|
|
|
# The code is *concise*, e.g., length/depth of method should not be too long; implement intermediate methods if necessary
|
|
|
# The code reuses utility methods and does not re-implement again and again similar features:
|
|
|
- The code implements similar features in a homogeneous way
|
|
|
- Look pro-actively for reuse, do not hesitate to talk to other members
|
|
|
- Good places to find reusable functionality are the "*.util" packages from each plugin
|
|
|
- ConQAT commons packages also contain many useful methods
|
|
|
# No magic constants are used, e.g.:
|
|
|
"`int i = 43 \* x`"
|
|
|
-> What does 43 mean? Use instead:
|
|
|
"`final int MULTIPLICATION\_FACTOR = 43;
|
|
|
int i = MULTIPLICATION\_FACTOR \* x;`"
|
|
|
Similar: "`return –2`"
|
|
|
# Using "get(0)" must be documented with an in-code comment stating why the "get(0)" is correct here, which means:
|
|
|
- justify that the list is not empty
|
|
|
- *and* justify that it is relevent to take the first element and not another
|
|
|
# Warning may NOT be suppressed. Only the following two exceptions apply:
|
|
|
- The suppressible warnings "rawtypes" and "unchecked" may be used everywhere in the code.
|
|
|
- In migrators, deprecation warnings may be suppressed.
|
|
|
# Catches are never empty (at least a log message is sent to the console)
|
|
|
# If an issue is supposed to be fixed in the release, then no TODO should refer to it
|
|
|
# No useless empty lines (typically before a closing brace)
|
|
|
# When an expression spans two lines or more, try using intermediate local variables to make it more readable
|
|
|
(note: this can be easily done by 1. selecting the expression for which you want to define an intermediate local variable and 2. using the Eclipse menu "Refactor->Extract Local Variable")
|
|
|
# When an expression is used several times, introduce a local variable
|
|
|
(note: this can be easily done by 1. selecting the expression for which you want to define an intermediate local variable and 2. using the Eclipse menu "Refactor->Extract Local Variable")
|
|
|
# In comments always use {`link class} when referencing a class
|
|
|
8. Method or attributes comments that fit one line should be one line,
|
|
|
i.e., do not do:
|
|
|
`/**`
|
|
|
@ \* Blah.@
|
|
|
@ \*/@
|
|
|
But:
|
|
|
`/** Blah. */`
|
|
|
9. Big classes and methods should be split
|
|
|
10. Classes and methods with similar functionality should be factorized
|
|
|
11. Use static imports for static methods (i.e., java.lang.Utils.blah
|
|
|
->blah): Mark method, `CTRL+SHIFT+M`. Can have exceptions for
|
|
|
non-utility classes.
|
|
|
12. No useless introduction of variables: if a variable is used only
|
|
|
once and the corresponding expression fits on one line then just do
|
|
|
not introduce the variable (note: removing such a variable can be
|
|
|
easily done using the Eclipse menu “Refactor->Inline”)
|
|
|
13. Comments should be concise (i.e., not explain the same thing twice,
|
|
|
and avoid explaining something which is obvious, ex: “@param comp -
|
|
|
The component”…)
|
|
|
|