# Code conventions

Focused responsibilities and project development conventions.

## Code Quality & Conventions

### Efficient development with agents

Agents should minimize context and command output. Search locally before
reading a large file, and use `docs:section` or `docs:search` for targeted
reference lookup. For bulk inspection, validation, or mechanical
transformations, create or reuse deterministic local scripts. Prefer scripts
that support dry runs and concise summaries.

Scripts can collect evidence and apply mechanical changes, but agents must
review the diff and make architectural decisions themselves. Do not delegate
judgment blindly to a script.

### Always use curly brackets

Every control-flow block - `if`, `else`, `foreach`, `while`, `for` - must use `{` and `}`, even for single-line bodies. This applies to both PHP and JavaScript.

```php
// correct
if ($value) {
    do_something();
}

// wrong
if ($value) do_something();
if ($value)
    do_something();
```

```javascript
// correct
if (value) {
    doSomething();
}

// wrong
if (value) doSomething();
```

PHP naming: **snake_case everywhere** - functions, variables, parameters, file names. No camelCase or PascalCase in PHP.

### Proper solutions over hacks

Always solve the underlying problem. If the right fix requires a refactor, do the refactor. Never paper over an issue with workarounds, conditional flags, or code that compensates for a broken assumption.

- If a template needs data that isn't available, fix the data loading - don't hardcode a fallback.
- If a field type doesn't support a use case, extend the field type - don't work around it in the template.
- If a layout breaks, fix the layout - don't hide the symptom with z-index tricks or overflow hacks.

A proper solution is always preferable to a hack, even when it takes more effort.

### Component architecture

When adding a self-contained feature to a project - a photo collage, an interactive map, a newsletter signup block, a countdown timer - build it as a component, not as inline code on a page.

In Nimbly, a component is a reusable template in `ext/tpl/<name>/`:

```
ext/tpl/photo-collage/index.tpl    ← template
ext/tpl/photo-collage/style.css    ← optional component CSS; import it from ext/theme.css
ext/tpl/interactive-map/index.tpl
```

Called from any page template with its shortcode name:

```
[#photo-collage#]
[#interactive-map location="Amsterdam"#]
```

Rules for components:

- **Self-contained** - all markup, logic, and scoped styles live inside the component directory. The page template only calls the shortcode.
- **Configurable via parameters** - use shortcode params for anything that varies per use (`[#map location="..." zoom="12"#]`). Do not hardcode values that belong to the caller.
- **No side effects** - a component should not assume what page it is on, what other components are present, or what CSS classes the parent defines.
- **Portable** - a well-built component can be copied to another `ext/` repo and used immediately without modification.

For most UI components a template is sufficient. Promote to a module (§14) only when you need to install a resource (e.g. an event system that creates an `events` resource on install) or register dedicated routes (e.g. `/event/(slug)/`). A photo collage, an interactive map, a countdown timer, a newsletter block - none of these need a module.

### Commit messages

Use the [Conventional Commits](https://www.conventionalcommits.org/) standard for commit messages. Keep messages short, specific, and professional. One line is almost always enough. No "Co-authored-by", no generated noise, no trailing metadata.

**Good:**
```
fix: prevent mobile h1 overflow and align hamburger
feat: add eventdates field with per-occurrence time and ticket info
style: reduce tablet section top padding to match mobile
```

**Bad:**
```
fix stuff
WIP
Update files
Fix mobile h1 overflow and hamburger alignment
Co-Authored-By: Claude <noreply@anthropic.com>
```

If more context is needed, add it as a second paragraph after a blank line - but the first line must stand alone and be specific.

---

## Template naming convention

Name every reusable template with the **partial type first**, followed by the route or subject it belongs to:

```
{type}-{route-or-subject}
```

Types and examples:

| Type | Used for | Example |
|------|----------|---------|
| `page-` | Full-page template (one per route) | `page-community-gamechangers`, `page-accelerator` |
| `section-` | A section or block rendered inside a page | `section-home-header`, `section-page-header` |
| `card-` | A repeatable card component | `card-alumni`, `card-network-partner` |
| `logo-` | A logo display component | `logo-partner`, `logo-partner-image` |
| `icon-` | An inline icon snippet | `icon-arrow-right`, `icon-chevron-right` |
| `form-` | A form component | `form-registration` |

Sub-templates inside a page directory follow the same rule - type first:

```
ext/tpl/page-community-networkpartners/
  card-cluster.tpl
  card-network-partner.tpl
  card-network-partner-logo.tpl
```

**Never** put the type at the end (`alumni-card`, `coalition-page`). Type-first keeps all cards, all sections, and all page templates sorted together in the filesystem.