JavaScript formatting / applied

Make code predictable.

Formatting is not decoration. It gives every kind of code a known address, makes names carry shape, and lets control flow read from top to bottom.

users_group_by_role.js
function users_group_by_role(users)
{
    const out = {};
    for (const user of users) {
        out[user.role] ??= [];
        out[user.role].push(user);
    }
    return out;
}

module.exports = users_group_by_role;

01A file has an address system.

Before reading a line, you should already know where dependencies, policy, behavior, helpers, and execution live.

01 / BIN
#!/usr/bin/env node
02 / DEPS
const cli = require('@vbarbarosh/node-helpers/src/cli');
const fs = require('node:fs');
03 / POLICY
const REPORT_LIMIT = 31;
04 / RUN
cli(main);
05 / ENTRY
function main()
{
    // public behavior
}
06 / HELP
function format_percent(value)
{
    return `${value}%`;
}

02Brace position reveals scope.

The unusual part is intentional: module-level declarations form landmarks; nested behavior stays visually compact.

Module scope brace moves down
function main()
{
    // top-level landmark
}

The brace creates a strong horizontal break before the file’s primary behavior.

Nested scope brace stays put
function main()
{
    function limit_print(limit) {
        console.log(limit);
    }
}

Nested declarations, callbacks, and control flow keep the brace on the declaration line.

03Names tell you what will happen.

A function is a verb phrase. Data is a noun phrase. The assignment reads like a small, testable sentence.

Behavior

Imperative verb markers announce an operation.

users_group_by_role(users)function
users_index_by_id(users)function
items_sort_by_time(items)function

Result

Noun shape and plurality announce what is stored.

users_by_roleRecord<role, User[]>
user_by_idRecord<id, User>
items_sorted_by_timeItem[]
const users_by_role = users_group_by_role(users);
usersPlural: one key can return many users.
_by_roleData lookup: bracket access, or .get() on a Map; never a function call.
_group_by_Verb marker: this side performs the grouping.

04Watch the rules change the code.

The result is longer by line count and shorter by interpretation time. Shape, mutation, and exit are all exposed.

Before compressed decisions
const group = (arr) =>
    arr.reduce((acc, x) => {
        (acc[x.role] ||= []).push(x);
        return acc;
    }, {});

const result = group(users);

module.exports = group;
Applied each decision gets a line
function users_group_by_role(users)
{
    const out = {};
    for (const user of users) {
        out[user.role] ??= [];
        out[user.role].push(user);
    }
    return out;
}

module.exports = users_group_by_role;

05Imperative flow reads downward.

No accumulator protocol to mentally execute. The loop says what exists, what is missing, what changes, and what leaves.

INPUT

Take users

The plural parameter states the incoming collection.

CONSTRUCT

Create out

The local return container has one conventional name.

ITERATE

Visit each user

for...of and singular user expose cardinality.

RETURN

Return out

The constructed result exits once, at the bottom.

06Objects carry only what crosses the boundary.

Explicit construction makes the output contract reviewable. A spread silently couples it to every future source field.

Implicit payload

The output grows whenever item grows.

return {...item, index};
uidparent_uidtokendebugindex

Declared payload

The output changes only when this code changes.

return {uid: item.uid, parent_uid: item.parent_uid, index};
uidparent_uidindex

07The 30-second review. scan top → bottom

1
Can I identify the file type?

A library ends with one export. A script hands main to cli(main); after globals.

2
Is the entry convention correct?

A script declares main first; a library uses a domain-first function name.

3
Do names reveal data shape?

Plurality, _by_, and _sorted_by_ agree with the value.

4
Does control flow read downward?

Guards return early; loops are explicit; deep pipelines are gone.

5
Is the constructed result named out?

The caller gives it the domain name after the function returns.

6
Are boundaries explicit?

Dependencies, object fields, helpers, and execution are visible.