Coding Standards

From Scantegrity Wiki

Scantegrity is written in Java, and our coding standards choices were highly influenced by the 2007 proposed Voluntary Voting System Guideline on this topic:

Application logic SHALL adhere to a published, credible set of coding rules, conventions or standards (herein simply called "coding conventions") that enhance the workmanship, security, integrity, testability, and maintainability of applications.

The rest of the Software Engineering section is dedicated to explaining what that means, but basically it comes down to "use what someone else has used, and you may modify it if those modifications enhance the code." You are encouraged to go take a look and read the whole section.

Because of this an many other reasons, the coding practices are standardized on Sun's Code Conventions for the Java Programming Language. It is a short (24 page) document that is very well written and highly recommended.

Additional Guidelines[edit]

There may or may not be other languages involved in the project. There are also a lot of other things to note that are ignored by the java code conventions linked above that we'd like to point out. Many of these are taken from the VVSG.

  • Modules should be small, clearly defined, and easily identified.
  • Each module should have a well defined testable behavior, and should have an accompanying test written for it.
  • Ignoring comments, blank lines, and other formatting, code in a function or other callable unit should not exceed 25 lines of logic. 180 lines is the absolute maximum size, and will only be considered in special cases.
  • Defined variables and tables should be in a file dedicated to that purpose.
  • Handle ALL exceptions using block-structured exception handling constructs (try-catch).
  • Wrap crappy API calls (and use the try/catch).
  • goto, intentional exceptions, ignoring exceptions, and other unstructured control flow are verboten.
  • Use proper locking.
  • No self-modifying code.
  • Always ALWAYS check your inputs.
  • Always fail gracefully, with good error messages.

Variable Naming: Prefixes[edit]

The project uses variable name prefixing (e.g. prepends standard tags to the beginning of variables to indicate scope). The prefixes are as follows:

  • p_  — parameters
  • c_  — class variable
  • l_  — local variable
  • g_  — global variable
  • d_  — compile-time defined variable, data from a big static table, etc.