StyleGuide

The beginnings of a style guide for Neat code.

Recommendations are given short-hand names for ease of reference.

Note: this guide is merely an attempt to document the "preferred Neat style". It is not normative!

DRY-1: Treat any repetitiousness as a code smell. When necessary, don't be afraid to modify the compiler to remove it.

IMPORT-1: When importing modules using the grouping syntax std.(file, time), order your imports so that all closing parentheses occur at the end. This helps readability as visual backtracking is not required to figure out the full import path.

Example:

import std.(file, time, lib.(freetype2, opengl.(, sdl))); // good
import std.(lib.(opengl.(, sdl), freetype2), file, time); // bad

SYNTAX-1: When choosing identifier names, consider using:

• ALLCAPS for compile-time variables, like template arguments (but not expression aliases)
• CamelCase for user-defined composite types, like structs and classes
• lowerCaseCamelCaps for functions
• lisp-style-identifiers for global variables.

STRINGS-1: Keep mutable strings local. Assume, unless you know better (for a fact), that strings you got as arguments are immutable. If you have to edit strings directly for performance reasons, make a local copy. This prevents spooky-action-at-a-distance type of bugs, and makes slices all-around safer and cheaper to use.

SYNTAX-2: Avoid tails. This is a generalization of IMPORT-1. A tail is any instance where significant information is "hidden" at the end of the function and separate from the rest. Generally, control flow decisions should be made as early as possible in the function. For instance, replace

if (auto res = foo()) {
  // lots of code;
  return something;
}
// This is the "tail", a piece of control flow that has
// nothing to do with the rest of the function.
return null;

with

auto res = foo();
if (!res) return null; // pulling the tail in front;
// lots of code