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: verb_noun_detail
• Examples:
  • transform_obsidian_to_astro.py
  • deploy_astro_site.sh
  • backup_database_incremental.py

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

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.