Naming System

General Philosophy

“Underscores for Files, Hyphens ONLY for URLs.”

We prioritize “Dev-First” consistency. Since hyphens break module imports in Python and complicate variable mapping, underscores (_) are the universal separator for all files and folders.

Naming Structure (Modified BEM)

Adapt the BEM system to be Underscore Exclusive:

• Block: The main object/context (PascalCase)
• Element: The specific part (PascalCase, prefix _)
• Modifier: Version or differentiator (PascalCase, prefix _)

Format: Block_Element_Modifier

Files & Folders

Global Rules

1. Separator: Use Underscores (_). No hyphens -.
2. No Spaces/Special Chars: Never use spaces, commas, or brackets.
3. Dates: If needed, suffix with _YYYYMMDD.

1. Documents & Assets (Human-Readable)

For PDFs, Markdown notes, Images, and Data files.

• Strategy: “PascalCase is the Glue, Underscores are the Hinge.”

• The Rule: Use PascalCase to group words into a single concept (Block or Element). Use Underscores only to separate the hierarchy (Category from Name, or Name from Version).

• Why: Separating every single word with an underscore (e.g., My_File_Name.pdf) makes filenames too long and creates “visual stutter.”

• Examples:

  • Articles/Sources:
    • ✅ Globe_BeatingTheTSX_20250403.pdf (Source _ Title _ Date)
    • ❌ Globe_Beating_The_TSX_20250403.pdf (Too many separators)
  • Projects/Brands:
    • ✅ SmartDebtCoach_v2.pdf (Brand _ Version)
    • ❌ Smart_Debt_Coach_v2.pdf (Brand name is fragmented)
  • Generic Documents:
    • ✅ CodingGuidelines_Common.md (Topic _ Scope)
    • ✅ FinancialReport_Q3_Draft.pdf (Type _ Period _ Status)

2. Software, Scripts & System Utilities (Machine-Readable)

For all code files, scripts, and generic system utilities.

• Case: snake_case (All lowercase separated by underscores).
• Why: Ensures compatibility with Python imports (import my_module) and creates consistency across Bash/Shell scripts.
• Location: D:\FSS\Software\Utils\
• Structure — the test: is this thing an action, or an artifact?
  • Action script (identity is the verb it performs — a one-shot operation you invoke): keep the verb. verb_noun_detail.
    • transform_obsidian_to_astro.py, deploy_astro_site.sh, backup_database_incremental.py
  • Artifact / tool / project (a thing that exists and does its job on demand — creation is implied, don’t restate it): noun only, no verb prefix.
    • folder_structure (not generate_folder_structure), orgchart (not create_org_chart)
  • Keep the dev project folder name and its KB registry note in sync: D:\FSS\Software\Utils\PythonUtils\folder_structure\ ↔ Core/IT/Utils/Custom/folder_structure.md.

Tool naming across kinds (skills, utils, scripts) — priority: semantic clarity, then conciseness

• Skills / slash commands (invoked as a command — /dept-init, /task-complete): hyphenated verb-noun, per AGENTS.md’s “name by what it does, not when it runs.” A skill’s identity is the action Talbot triggers.
• Custom utils / standalone tools (a project that exists and is run, not a single invoked command — folder_structure, pdftext, job_monitor): snake_case noun (or noun_noun), no verb prefix — same rule as artifacts above.
• One-shot action scripts inside a project (a script that does one destructive/transform action — deploy_astro_site.sh): keep the verb.
• Why the split holds: a skill is something you do; a util is something that exists. Naming both as verbs collapses that distinction and adds a word with zero information (running a tool implies it does something).

3. Web Development (The “Slug” Exception)

There is exactly one exception to the “No Hyphens” rule: Public-facing URLs.

• File Names: Remain snake_case or PascalCase depending on the framework (e.g., user_profile.tsx or UserProfile.tsx).
• Routes/Slugs: When the file is mapped to a URL, the browser path must use hyphens for SEO.
  • File on Disk: pages/financial_leverage.md
  • Public URL: www.smartdebtcoach.com/resources/financial-leverage

4. Reference Artifacts (Bills, Receipts, Statements) — ISO Date Exception

Dated financial docs get one more hyphen exception: the date only.

• Rule: Type_Vendor_YYYY-MM-DD.pdf — what → who → when. Hyphens in the date (ISO-8601, sortable, never a code var — the “hyphen=subtraction” concern doesn’t apply).
• Folder-implied collapse: drop any element the folder already says — Type (Bills/, single-purpose Expenses/AI Tools/) or part of Vendor (Statements/CreditCard/ already says “CreditCard” — don’t repeat it in the filename). Only keep what the folder doesn’t tell you (which institution — stays useful if the provider changes, e.g. switching card issuers).
• Precedent: matches 8yr-old Bills/ convention (Rogers-2018-10-16.pdf) — already right, now codified.
• Examples:
  • ✅ Rogers_2026-07-16.pdf (Bills/ implies Type)
  • ✅ Claude_2026-07-16.pdf (single-purpose folder)
  • ✅ BMO_2026-07-30.pdf (Statements/CreditCard/ — folder already says “CreditCard”; institution is the only new info)
  • ✅ Receipt_ShannonBurnham_2015-03-20.pdf (Invoices/ mixed — holds invoices + receipts, Type kept)
  • ❌ Receipt-2016-4026-4585.pdf (opaque, no vendor/date)
  • ❌ April 30, 2026.pdf (no vendor, spaces+comma)
• Investment accounts (multi-account folders): date can drop the day (YYYY-MM only) when the statement already carries its exact date inside — shorter is better once the folder-implied collapse rule is satisfied. Vendor comes first, then the account number (a second identifying field the folder doesn’t imply, since one folder can hold several accounts): Vendor_Account_YYYY-MM.pdf (e.g. BMO_21414578_2025-06.pdf).
• Subtype suffix: when a document isn’t the folder’s default/primary statement (e.g. a yearly-performance summary alongside monthly statements), suffix the rootname with the subtype, placed after the account and before the date: Vendor_Account_Subtype_YYYY-MM.pdf (e.g. WS_WK69DHD01CAD_Yearly_Performance_2025-06.pdf). Don’t suffix the default/primary type (no _Statement needed) — only distinguish the exception.

Coding Standards

Goal: World-class, maintainable code.

• Self-documenting: Prefer descriptive names (index_color over i).
• Consistency: Adhere to the patterns below.

Language Specifics

Python (PEP 8 Strict)

• Modules/Scripts: snake_case (e.g., data_processor.py) (CRITICAL: No hyphens)
• Variables/Functions: snake_case (e.g., calculate_total_value)
• Classes: PascalCase (e.g., class DataProcessor:)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRY_COUNT = 5)

JavaScript / TypeScript

• Files: snake_case (user_utils.js) or PascalCase (UserProfile.js) are acceptable, but avoid hyphens.
• Variables/Functions: camelCase (e.g., let itemCount = 5)
• Classes/Components: PascalCase (e.g., function UserProfile())
• Constants: UPPER_SNAKE_CASE for true constants; camelCase for reassignable refs.

CSS

• Files: main_styles.css (Underscore preferred for file consistency).
• Classes/IDs: kebab-case is the industry standard for selectors inside the file.
  • Example: .nav-menu, #main-content
• BEM inside CSS:
  • .block__element--modifier (Standard BEM syntax uses double underscores/hyphens strictly within CSS selectors, which is fine as this is code, not a filename).
• Variables: --kebab-case (e.g., --color-primary).

---

Why Underscores Only?

We standardized on the underscore (_) because it is the only separator that passes the “Universal Safety Test” across all computing contexts.

1. Code Compatibility (The “Math” Problem):

   • Hyphens (-) are interpreted as subtraction in almost every programming language.
   • Fails: import my-script (Python sees: import my minus script).
   • Works: import my_script.
   • Benefit: A file named with underscores can be instantly dropped into a script as a variable or module name without renaming.

2. Selection Efficiency:

   • In editors and terminals, double-clicking a hyphenated name (file-name) selects only one word.
   • Double-clicking an underscored name (file_name) selects the entire string.

3. Lack of Safe Alternatives:

   • Hyphens: Great for URLs, fatal for code variables.
   • Dots (.): Confuse OS file extension logic (e.g., file.v1.pdf) or hide files on Unix (.config).
   • Commas (,): Reserved chars in Python, JS; CSV data corruption; unsafe in URLs
   • Spaces: Require escaping in command lines (cd my\ folder) and break web links.
   • Plus (+): interpreted as an encoded space in URLs.

The Verdict: The underscore is the only character that lets a filename exist as a document, a web asset, a command-line argument, and a code variable simultaneously without modification.