Skip to main content

General Rules

The following is a list of language-agnostic development rules that should be followed when working within any Rizing development project.

note

Rules related to specific languages can be found under the Standards drop-down.

Variables​

Use meaningful variable names​

Distinguish names in such a way that the reader knows what the differences offer.

Bad: 
function between(a1, a2, a3) {
  return a2 <= a1 && a1 <= a3;
}
Good: 
function between(testValue, rangeMin, rangeMax) {
  return rangeMin <= testValue && testValue <= rangeMax;
}

Use pronounceable variable names​

If you can’t pronounce it, you can’t discuss it without sounding like an idiot.

Bad: 
type DtaRcrd102 = {
  genymdhms: Date;
  modymdhms: Date;
  pszqint: number;
};
Good: 
type Customer = {
  generationTimestamp: Date;
  modificationTimestamp: Date;
  recordId: number;
};

Use the same vocabulary for the same type of variable​

Bad: 
function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;
Good: 
function getUser(): User;

Use searchable names​

We will read more code than we will ever write. It's important that the code we do write is readable and searchable. By not naming variables that end up being meaningful for understanding our program, we hurt our readers. Make your names searchable.

Bad: 
// What the heck is 86400000 for?
setTimeout(restart, 86400000);
Good: 
// Declare them as capitalized named constants.
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;

setTimeout(restart, MILLISECONDS_IN_A_DAY);

Use explanatory variables​

Bad: 
declare const users: Map<string, User>;

for (const keyValue of users) {
  // iterate through users map
}
Good: 
declare const users: Map<string, User>;

for (const [id, user] of users) {
  // iterate through users map
}

Avoid Mental Mapping​

Explicit is better than implicit.
Clarity is king.

Bad: 
const u = getUser();
const s = getSubscription();
const t = charge(u, s);
Good: 
const user = getUser();
const subscription = getSubscription();
const transaction = charge(user, subscription);

Don't add unneeded context​

If your class/type/object name tells you something, don't repeat that in your variable name.

Bad: 
type Car = {
  carMake: string;
  carModel: string;
  carColor: string;
};

function print(car: Car): void {
  console.log(`${car.carMake} ${car.carModel} (${car.carColor})`);
}
Good: 
type Car = {
  make: string;
  model: string;
  color: string;
};

function print(car: Car): void {
  console.log(`${car.make} ${car.model} (${car.color})`);
}