forked from kframework/k-legacy
-
Notifications
You must be signed in to change notification settings - Fork 0
Style Guidelines
dwightguth edited this page Mar 12, 2014
·
2 revisions
- No trailing whitespace (even on blank lines)
- All indentation for code blocks are four spaces (no tabs)
- Whenever a line is wrapped due to length, all lines subsequent to the first shall have a hanging indent of four spaces (no tabs).
- No line shall be longer in length than 99 characters, except import statements, which shall be on a single line each.
- Curly brackets for blocks shall begin on the same line containing the statement that started the block, and shall end on a new line (or the same line as a keyword delimiting a new block part of the same statement, e.g. else).
- The first statement of a block in curly brackets shall begin on a new line.
- All control-flow statements with nested blocks shall use curly brackets to delimit the blocks, unless the entire statement and all of its blocks can fit on a single line.
- In between method declarations and inner class declarations in a class there shall be exactly one line of whitespace.
- All fields in a class shall be at the top of the class, above any method declarations or constructors, unless they deal specifically with only one method, in which case they may be adjacent to that method.
- All constructors in a class shall be at the top of the class, immediately below any fields, but above any method declarations.
- All fields that do not have javadocs shall be in a single block with no blank lines between them, or a set of logical blocks with a single blank line separating each block, and no blank lines within the block.
- All fields with javadocs shall be separated from one another by a single blank line.
- Blank lines shall be used inside functions only to separate logical portions of the function, and only one blank line at a time.
- There shall be no use of "import .*" unless enumerating all the fields used in the class from that package would require enumerating the vast majority of the classes in the package, of which there are a significant number.
- All classes used in a file from outside the package shall be imported rather than referenced with their fully qualified package path, unless to import them would cause an unavoidable namespace conflict.
- New classes should endeavor at all costs to avoid possessing the same name as a common Java standard library class, or a class in another package of the repository. The only exceptions are classes where obeying this rule would force a completely unnatural class name.
- Imports within a single top-level domain shall be in alphabetical order with no blank lines betwen them.
- Imports from separate top-level domains shall have a single blank line to separate them.
- Because the k framework is a part of the "org" top-level domain, "org" imports shall be on top, followed by all third-party top-level domains, followed by the java and javax top-level domains.
- No public function shall have its functionality influenced by the value of a non-constant static variable. Thus, all static variables must either be declared final and initialized to an immutable type, or else be private and only used for purposes which have no impact on the semantics of any public API (e.g. caching).
- No inner class shall fail to be static unless it relies upon instance fields of its parent class. Thus, there are only three cases where inner classes are acceptable: the first is if it would be nontrivial to separate the class from its parent elegantly, because of its use of state from the parent class. The second is if the class is private, and therefore only exists to provide functionality to its parent class. And the third is if the inner class is a clearly related conceptual piece of the outer class, for example a Grammar object and its representation of a nonterminal.
- Any code which commits an implementation of functionality which is imperfect and designed to be fixed latter shall be commented with a TODO that provides your user alias. For example, if I make such a commit, I should add a comment beginning with "// TODO(DwightG):" and proceeding to explain what needs to eventually be modified about the code.
- All comments to the extent that a particular change needs to be made at some point in the future shall be treated as instances of rule #22 and subject to its format guidelines.
- Changes to the style of code which do not alter any code itself will only be accepted if they fix explicit violations of this policy.
- NEW Expressions which are complex in nature will be rejected if they are not also easy to read. In particular, an expression which is complex due to a large amount of boilerplate code intermixed with the meaning of the expression will be rejected and the committer will be asked to modify the method interface that they are calling to make the method more readable.