Code

A collection of "how we work" resources, including our code style manuals.

More here: https://github.com/NUKnightLab/how-we-work/tree/master/standards

TL;DR

A quick summary of our code style for the impatient

All languages

  • 4-space, soft-tab indents
  • 80-character line lengths where practical
  • no trailing whitespace
  • blank lines between major blocks (functions, modules, classes) but not generally within them
  • naming:
    • prefer words to abbreviations to single letters. Exceptions for “throw-away” variables (e.g. i,j loops)
    • only begin with lowercase letters or _, except for class names
    • TODO: How to handle acronyms like HTML, PDF, URL ?

Python

  • PEP8
  • naming
    • snake_case variables, functions, and methods
    • PascalCase classes
    • avoid name-mangled dunder privates. In general, use dunders only for conventional and language-specific cases (init, pycache, etc.)

Javascript

  • 1TBS brace styling
    • { goes on end of block def line
    • } on own line, aligned with block
    • Don’t skimp on braces for single-line statements
    • cuddle else
    • space before brace
  • naming
    • camelCase functions and variables
    • PascalCase functions (?) and classes (um?) # TODO: this needs attention

Coding Standards

More here: https://github.com/NUKnightLab/how-we-work/tree/master/standards

JavaScript

Indent style conventions

  • 4 space indents
  • no hard tabs. Set soft tabs in your editor

brace placement

  • opening brace on end of block starting line
  • closing brace on line by itself
  • closing brace indented to align with block start

    e.g.

    
if (someCondition) {
    doSomething();
}

Line length

  • 80 character rule-of-thumb

In general, try to keep lines around 80 characters or less. We will probably not be as vigilant in Javascript as in Python regarding line length, but a long line should have a pretty good reason.

Naming conventions

  • camelCase variable names
  • camelCase or PascalCase function names <-- which do we use?

Commenting

function declarations

  • In general, function literal style instead of standard function declarations.

    E.g.:

    
var myFunction = function() {
    // do something here
};

Git Commits

Keep your commit messages simple and succinct

  • Concise, frequent, descriptive comments as a rule
  • A single line no more than 50 characters

If you must have a longer message:

  • Separate the body from the subject with a blank line
  • Wrap body at 72 characters
  • Describe what and why vs. how

However, note that if you are needing to write long commit messages, you probably need to commit more often.

Documentation Needed for:

  • Git - when to branch, commit, pull request
  • commit messages - utilize # and @
  • Rebase vs Merging. Do we want merge commits?
  • Squashing commits and making sure commits are tied to features, bugs etc

Resources/References

Multi-language/language independent

  • (MOZ) Mozilla Code conventions
    Not definitive, but can be used as a broader reference if needed. They get some things wrong. The brace style they define is not K&R as stated. It is 1TBS, which is what we will be using

Javascript

Python

CSS/Sass (We need to pick one)