Syntax

  • nodejs vs. bash vs. ruby vs. some other language; it does not matter as each has its value. Use the appropriate language for the job and follow this guide.
  • Always write tests using roundup where necessary.
  • Create man pages when further explanation is required and --help flag won't cut it.
  • Wrap all scripts in a function. If necessary, call function passing in arguments at the end of the file.
  • All variables declared in a function should be set as local.
  • Include fallback mechanism for invalid options passed or missing arguments.
  • Abstract into functions where necessary.

Exit Codes

All clients should return some exit code. Use the following table for reasons and why:

Value Status
0Success
1General error; typically a bad flag or value
2Missing dependency

Comments

Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others. Great code comments convey context or purpose. Do not simply reiterate a component or class name.

Be sure to write in complete sentences for larger comments and succinct phrases for general notes. And avoid journal style comments in favor of better commit messages and git log for history.

Comments are not meant to replace version control, so don't comment out code or mark to do later; remove it and create a commit in history.

Organization

  • We tend to read code from top-to-bottom, like a newspaper. Because of this, make your code read that way. e.g. if a function calls another, keep those functions vertically close in the source file. Ideally, keep the caller right above the callee.
  • Organize sections of code by component.
  • Develop a consistent commenting hierarchy.
  • Use consistent white space to your advantage when separating sections of code for scanning larger documents.