Fgts Naming Convention

FGTS — From General To Specific

A deterministic, scope-descending identifier system for files, variables, configs, and APIs · v1.0

Core Principle

Every identifier is a path through a conceptual namespace, moving from the broadest context down to the most specific detail. Reading left to right is like zooming in on a map — each segment narrows the scope of the one before it.

This makes names sortable, groupable, and self-documenting without external tooling. The convention applies uniformly to filenames, variables, config keys, API routes, and database fields.

Segment Anatomy

<domain>_<system>_<entity>_<attribute>_<qualifier>

Canonical example:

net_flow_iface_bytes_in
│   │    │     │     └─ qualifier : inbound direction
│   │    │     └─────── attribute : byte count
│   │    └───────────── entity    : network interface
│   └────────────────── system    : NetFlow pipeline
└────────────────────── domain    : network monitoring

Segments are separated by _ (snake_case). Use - (kebab-case) for filenames and URLs. Omit trailing segments when specificity is unambiguous in context.

Rules

1. Left-to-right specificity is mandatory. Never place a narrower segment before a broader one. auth_session_user_id is valid; id_user_session_auth is not.

2. All lowercase, no spaces. Snake_case for code identifiers; kebab-case for file paths and URLs. Mixed case within segments is forbidden.

3. Use abbreviations consistently. Establish a project-level glossary (e.g. ts = timestamp, cnt = count, cfg = config). Never mix abbreviated and full forms of the same word.

4. Omit obvious segments. Inside the auth module, session_id is sufficient — prepending auth_ is redundant. Apply the innermost-scope rule.

5. No verbs in data names. Verbs belong in function/method names. Data identifiers describe what a thing is, not what you do with it. db_query_result_rows not db_get_query_rows.

6. Qualifiers are the last resort. Only add a Level 5 qualifier when the attribute is genuinely ambiguous without it. bytes_in vs bytes_out is valid. count_final is a smell.

7. Plural only at the entity level. net_flow_ifaces_count — the entity (ifaces) is plural because it's a collection. Attributes and qualifiers stay singular.

Examples by Context

Good vs. Bad

✗ Violations

getFlowBytesIn          # verb prefix + camelCase — wrong casing, wrong order
in_bytes_iface_net      # reversed specificity — qualifier before domain
iface_bytes             # missing domain context — collides across systems
netFlowIfaceByteIn      # camelCase — reserved for method/function names

✓ Correct

net_flow_iface_bytes_in       # all five levels, left-to-right, snake_case
net_flow_iface_bytes_out      # parallel structure — differs only at qualifier
net_flow_iface_pkt_cnt        # abbreviation used consistently per glossary
flow_iface_bytes_in           # domain omitted — valid inside a net-scoped module
net-flow-iface-report.md      # kebab-case for filename; same hierarchy

Starter Abbreviation Glossary

FGTS Naming Convention · From General To Specific · v1.0 · 2026