Below are comments on each rule in relation to the existing Scale Java® code. One rule (36) we feel is just plain wrong. Another rule (64) we feel is poor. We have added comments concerning many of the other rules in regards to the use of the rule in Scale. For the other rules not referenced you can assume that we agree with it while Scale may or may not adhere to it completely.
Unfortunately, we can not include the actual rule here. You will have to go out and buy the book.
1. Please! Adhere to the coding style that is used throughout Scale. Make the effort to learn the style in use.
2. Give a thought to the person(s) who will end up maintaining your stuff. Unless, of course, you wish to be that person for the rest of your life.
3. Don't we all wish we could write it right the first time every time. But, we can at least try by not knowingly violating known principals.
4. Oops - perhaps we can add this documentation of deviations later ;->
5. Scale uses two spaces as an indent.
We also do not exactly follow the indenting standard for certain Java® constructs. For example, scale indents methods and classes as
public void method()
{
..
}
For else, else if, and catch the Scale code does
if (exp) {
...
} else if (exp) {
...
} else {
...
}
6. Never, ever place more than one semicolon on the same line!
Always make the assignment operator (=) the primary operator in a statement.
For eample, the code
if ((a = exp) == null) {
...
}
is just awful. It should be written as
a = exp;
if (a == null) {
...
}
to make it easy to see the assignment.
7. This rule is very important. Use whitespace copiously. Nothing is harder to read than a congealed mass of ASCII text all munged together.
8. We don't really use hard tabs. By default, Emacs does. Naughty emacs.
9. Using meaningful names goes a long way to making the code readable. However, some people carry this naming too far. For example, which is more readable:
for (int indexOverArrayA = 0; indexOverArrayA < n; indexOverArrayA++) {
...
... a[indexOverArrayA] ...
}
or
for (int i = 0; i < n; i++) {
...
... a[i] ...
}
Use an unimportant name for an unimportant variable - see rule 28. (Using i,j,k,l,m, and n for loop indexes is
an old Fortran habit.)
10. We should have used the name CfgNode instead of Chord.
12. Use only standard acronyms. Don't make up new ones by dropping vowels.
13. Someday all occurrences of CFG in Scale names will be changed to Cfg.
14. Scale may contain some examples of names that differ only in case. They will be eliminated as each is found.
15. Somehow using edu.umass.cs.ali.scale as a package name did not appeal to us. Besides, conforming to this rule would be a massive change.
21. We try to avoid interfaces because of the performance cost. We do use interfaces for the visit pattern.
29. We believe using this with every member reference is onerous. We do use this in the constructor and write access methods to avoid
ambiguity (see rule 30).
32. Write your documentation the way you would want others to write theirs for you.
33. We plead nolo contendre. We will make more of an effort to keep code and comments in-synch.
36. This rule is WRONG. Use // at the beginning of the line to hide the line. (The Emacs editor has a function that makes this easy.)
The standard comment form (/* ... */)
can not be applied to every line without modifying the line while // can be applied to every line.
37. If you use one-line comments, make them useful. Saying what the next statement does is often not useful. For example, in the code
// Call the xyz method. q.xyz(abc);the comment is NOT useful. See rule 61.
39. Most definitely. All methods and members should have javadoc-style comments. The method may be private now and public later.
63. We have used comments like /****** comment *****/ to note incorrect or incomplete code in the past. We should develop a better convention
64. No, no, no! Adding a comment on the closing brace makes the code more un-readable. If you write short code sequences, these comments will not be needed anyway. Use a good code browser to find the paired delimiter otherwise. Modifying code using these comments is more difficult too.
65. Adding a fall-through comment in switch cases where appropriate is on the list of things to we do when we find fall-through code.
66. Commenting empty statements is on the list of things we do when we encounter them.
67. Methods from a final class can be inlined so classes should be made final if possible.
69. Question - are the Scale classes too big for a compiler? We believe we use as small of classes as possible.
71. We use public members in private classes.
72. At every chance we eliminate occurrences of instanceof when that does not
result in placing application-specific code in a more general class. This is why we use the visit pattern.
73. We may benefit from observing this rule which has been ignored so far. For example, we often use a Vector of Declarations.
Having a DeclVector class would increase type safety. When we move to jdk 1.5, we can use the new features that make this easier.
74. We used to encapsulate enumeration values in their own classes. We eliminated every such instance from the Scale compiler for several reasons:
bytes instead of object references.
76. Sometimes we think the code is more readable without the extra braces. We prefer
if (condition)
statement;
to
if (condition) {
statement;
}
77. We are firm believers in fully parenthesizing an expression. Who can remember those numerous precedence rules anyway? Certainly not an old APLer.
79. We went to great effort, in the interest of performance, to insure that == could be used instead of .equals() for some class instances.
80. Sometimes it is just not possible in Scale to create an instance of a class that is valid immediately. We often have to create the instance and then add information to it to make it valid.
One example is when some instance is created without a Type which is added later.
81. We should definitely check for occurrences where a non-final method is called from a constructor and eliminate them.
83. Sometimes we explicitly check for errors, instead of allowing the JVM to detect them, so that we can generate a meaningful error report.
87. We silently absorb exceptions from the Omega Library.
89. Use the Java assert statement:
assert (condition) : message + instance.toString();
90. Use assert statements.