rules

Rules for naming files, functions, classes, methods, variables, etc.

License stars

Everything should look uniform

The generic advice is as follows: write new code in the same way the existing code is written.

If something isn’t explicitly specified, it doesn’t mean it’s not important. The naming of files, functions, CSS classes, formatting, and even the order of attributes are all important and should follow the same systematic approach. It’s just not written down.

Natural Pairs

Phrases

Intermittent failures

Intermittent failures are failures that happen sometimes, but not always, and usually cannot be reproduced consistently.

They appear to be random or unpredictable — sometimes the system works perfectly, and sometimes it fails — even though you didn’t change anything.

In other words:

This inconsistency is what makes intermittent failures annoying and hard to debug.

Common Causes

Intermittent failures usually come from:

Why They Are Painful

Because:

Example

// Sometimes fetch() returns slow, causing timeout.
// Sometimes it's fast. So the test occasionally fails.
test("API returns data", async function () {
    const data = await fetch("/api/data");
    expect(data.ok).toBe(true);
});

If network is slow → test fails If network is normal → test passes → intermittent failure

Common Patterns

value / label

For lists of selectable options (select, dropdown, radio, tabs, etc.) always use:

{value: <internal>, label: <display>}

Data Collection Naming Grammar

Form Meaning
*_group_by_* a verb/operation (function that performs grouping)
*_grouped_by_* a noun/grouped result (data structure)

References

const inventory = [
  {name: 'asparagus', type: 'vegetables', quantity: 9},
  {name: 'bananas', type: 'fruit', quantity: 5},
  {name: 'goat', type: 'meat', quantity: 23},
  {name: 'cherries', type: 'fruit', quantity: 12},
  {name: 'fish', type: 'meat', quantity: 22},
];
console.log(Object.groupBy(inventory, v => v.type));
console.log(Map.groupBy(inventory, v => v.type));

const items_grouped_by_anim = items_group_by_anim(items);

Collections

A variable named as a plural noun represents an array of rows:

item_types
users
banners

Shape:

Row[]

Indexed Collections

When a collection is reindexed by a unique property:

item_types_by_name
users_by_id
banners_by_uid

Shape:

Record<key, Row>

Rule:

<table_plural>_by_<unique_property>

This means:

Grouped Collections

When multiple rows can share the same property:

banners_grouped_by_status
users_grouped_by_role

Shape:

Record<key, Row[]>

Rule:

<table_plural>_grouped_by_<property>

Lookup Functions

When exposing behavior instead of structure:

item_type_by_name(name)
user_by_id(id)
banner_by_uid(uid)

Rule:

<singular_table>_by_<property>(property)

This performs lookup and typically wraps an indexed collection.

Derived / Constructed Values

Use _from_ only when something is computed, parsed, or constructed:

item_type_from_json(data)
user_from_token(token)
date_from_timestamp(ts)

Rule:

<singular>_from_<input>

Do not use _from_ for indexing.

Summary

Shape Naming
Array item_types
Indexed map item_types_by_name
Grouped map item_types_grouped_by_status
Lookup fn item_type_by_name(name)
Derived value item_type_from_json(data)
This site is open source. Improve this page.