drupal-standards

# Drupal Coding Standards

Apply Drupal coding standards based on the development context.

## Core Principles

From `coding_standards/index.md`:
- All code must follow Drupal coding standards (version-independent)
- Use US English spelling in all comments and names
- Standards are "always-current" and apply to all new code
- Follow Boy Scout Rule: leave code better than you found it

## Context Detection & Standard Loading

### PHP Development (.php files, modules, services, plugins)

When working with PHP code, **ALWAYS read these standards FIRST**:

1. **Core Standards**: Read `coding_standards/php/coding.md`
2. **Documentation**: Read `coding_standards/php/documentation.md`
3. **Namespaces**: Read `coding_standards/php/namespaces.md`
4. **PSR-4**: Read `coding_standards/php/psr4.md`

Additionally, based on specific needs:
- Creating services → Read `coding_standards/php/naming-services.md`
- Exception handling → Read `coding_standards/php/exceptions.md`
- Using placeholders → Read `coding_standards/php/placeholders-delimiters.md`
- Error handling → Read `coding_standards/php/e_all.md`
- Documentation examples → Read `coding_standards/php/documentation-examples.md`

### JavaScript Development (.js files)

**ALWAYS read these standards FIRST**:

1. **Core Standards**: Read `coding_standards/javascript/coding.md`
2. **Documentation**: Read `coding_standards/javascript/documentation.md`
3. **Best Practices**: Read `coding_standards/javascript/best-practice.md`
4. **ESLint Config**: Read `coding_standards/javascript/eslint.md`

If using jQuery:
- Read `coding_standards/javascript/jquery.md`

### CSS Development (.css, .scss files, styling)

**ALWAYS read these standards FIRST**:

1. **Core Standards**: Read `coding_standards/css/coding.md`
2. **Formatting**: Read `coding_standards/css/format.md`
3. **File Organization**: Read `coding_standards/css/file-organization.md`
4. **Architecture**: Read `coding_standards/css/architecture.md`

For tool configuration:
- Read `coding_standards/css/csscomb.md`
- Read `coding_standards/css/review.md`

### SQL Queries (database operations)

**ALWAYS read these standards FIRST**:

1. **Conventions**: Read `coding_standards/sql/conventions.md`
2. **Keywords**: Read `coding_standards/sql/keywords.md`
3. **SELECT Queries**: Read `coding_standards/sql/select-from.md`

### Twig Templates (.twig files)

**ALWAYS read these standards**:

1. **Twig Standards**: Read `coding_standards/twig/coding.md`
2. **Markup Standards**: Read `coding_standards/markup/style.md`

### YAML Configuration (.yml, .yaml files)

**ALWAYS read**:
- Read `coding_standards/yaml/configuration-files.md`

### Composer Packages (composer.json)

**ALWAYS read**:
- Read `coding_standards/composer/package-name.md`

### Accessibility (forms, UI components, interactive elements)

**ALWAYS read**:
- Read `coding_standards/accessibility/accessibility.md`

### Spelling & General

**ALWAYS apply**:
- Read `coding_standards/spelling/spelling.md` (US English required)

## Workflow

```
1. User requests development task
   ↓
2. Identify file types/context (PHP, JS, CSS, SQL, etc.)
   ↓
3. Read ALL relevant standard files from coding_standards/
   ↓
4. Apply standards while writing code
   ↓
5. Validate code against standards
   ↓
6. Complete task with compliant code
```

## Multi-Context Tasks

For tasks involving multiple file types, load **ALL** relevant standards:

**Example: Creating a custom module**
- PHP standards (module code)
- JavaScript standards (if includes JS)
- CSS standards (if includes styling)
- Twig standards (if includes templates)
- YAML standards (for .info.yml and config files)
- Accessibility standards (if includes UI)

## Application Rules

1. **Read First, Write Second**: Always read relevant standards before generating code
2. **No Assumptions**: Never assume standards—always verify from files
3. **Exact Compliance**: Follow standards exactly as written
4. **US English Only**: All comments, variable names, and documentation
5. **Complete Coverage**: If working with multiple file types, apply all relevant standards
6. **Validation**: Before completing, verify code against loaded standards

## Examples

### Example 1: Creating a PHP Service

```
User: "Create a service to handle user notifications"

Actions:
1. Identify: PHP service development
2. Read standards:
   - coding_standards/php/coding.md
   - coding_standards/php/documentation.md
   - coding_standards/php/namespaces.md
   - coding_standards/php/naming-services.md
3. Generate code following all standards
4. Include proper docblocks, namespaces, service naming
```

### Example 2: Writing Database Query

```
User: "Write a query to get active users with roles"

Actions:
1. Identify: SQL query
2. Read standards:
   - coding_standards/sql/conventions.md
   - coding_standards/sql/keywords.md
   - coding_standards/sql/select-from.md
3. Write query with proper keyword capitalization and formatting
```

### Example 3: Building an Accessible Form

```
User: "Create a contact form with validation"

Actions:
1. Identify: Multi-context (PHP form API, JavaScript validation, accessibility)
2. Read standards:
   - coding_standards/php/coding.md
   - coding_standards/php/documentation.md
   - coding_standards/javascript/coding.md
   - coding_standards/markup/style.md
   - coding_standards/accessibility/accessibility.md
3. Build form with all standards applied
4. Ensure full accessibility compliance
```

## Critical Reminders

- **Never skip reading standards** - always load them before coding
- **Standards override preferences** - follow Drupal standards exactly
- **When uncertain** - read additional related standard files
- **Multi-file tasks** - load standards for ALL file types involved
- **US English spelling** - non-negotiable requirement