Team Coding Standards

Unified coding standards and collaboration practices for WordPress development teams.

Core Principles

1. Code Quality First

• Write code that your teammates will thank you for
• If it's hard to explain, it's probably too complex
• Leave the codebase better than you found it

2. Communication is Key

• Comment the "why", not the "what"
• Use descriptive names that tell a story
• Document decisions in commit messages

3. Review with Kindness

• Assume positive intent
• Suggest improvements, don't demand them
• Celebrate good solutions

WordPress Coding Standards

PHP Conventions

<?php
/**
 * Function description.
 *
 * @since 1.0.0
 *
 * @param int    $post_id Post ID.
 * @param string $context Optional. Context for the action. Default 'view'.
 * @return array|WP_Error Data array on success, WP_Error on failure.
 */
function prefix_get_post_data( $post_id, $context = 'view' ) {
    // Validate input early.
    if ( ! $post_id || $post_id < 1 ) {
        return new WP_Error( 'invalid_id', __( 'Invalid post ID provided.', 'textdomain' ) );
    }

    // Check capabilities.
    if ( 'edit' === $context && ! current_user_can( 'edit_post', $post_id ) ) {
        return new WP_Error( 'unauthorized', __( 'You do not have permission to edit this post.', 'textdomain' ) );
    }

    // Get the post.
    $post = get_post( $post_id );

    if ( ! $post ) {
        return new WP_Error( 'not_found', __( 'Post not found.', 'textdomain' ) );
    }

    return array(
        'id'      => $post->ID,
        'title'   => $post->post_title,
        'content' => $post->post_content,
    );
}

Naming Conventions

File Organization

plugin-name/
├── plugin-name.php          # Main file, minimal code
├── includes/
│   ├── class-plugin-name.php    # Main class
│   ├── class-admin.php          # Admin functionality
│   ├── class-public.php         # Frontend functionality
│   └── functions.php            # Helper functions
├── admin/
│   └── views/                   # Admin templates
├── public/
│   └── views/                   # Frontend templates
├── assets/
│   ├── css/
│   ├── js/
│   └── images/
└── languages/

Security Checklist (Every PR)

Input/Output

• All user input sanitized (sanitize_text_field(), absint(), etc.)
• All output escaped (esc_html(), esc_attr(), esc_url())
• SQL queries use $wpdb->prepare()
• File paths validated against allowed locations

Authentication

• Forms include nonce fields (wp_nonce_field())
• Form handlers verify nonce (wp_verify_nonce())
• Capability checks before actions (current_user_can())
• AJAX handlers use check_ajax_referer()

Data Protection

• No sensitive data in error messages
• No debug output in production code
• API keys stored in options, not hardcoded
• User data handling follows privacy practices

Code Review Process

Before Submitting PR

1. Self-Review Checklist

   • Code follows team standards
   • Security checklist passed
   • No var_dump(), console.log() left behind
   • Functions are under 50 lines
   • Complex logic has comments explaining "why"

2. Test Locally

   • Works in target environment
   • No PHP errors/warnings
   • No JavaScript console errors
   • Tested on mobile (if frontend)

3. Write Good PR Description

   • What does this change?
   • Why is it needed?
   • How can it be tested?
   • Any concerns or areas to focus review?

Reviewing Others' Code

Tone Guidelines:

• ✅ "What do you think about using X here? It might help with Y."
• ✅ "Nice solution! One small suggestion..."
• ✅ "I'm curious about this approach - could you explain the reasoning?"
• ❌ "This is wrong."
• ❌ "You should have done X."
• ❌ "Why didn't you just...?"

Focus Areas:

1. Security - Always check first
2. Logic - Does it do what it should?
3. Performance - Any obvious issues?
4. Maintainability - Will future devs understand?
5. Standards - Follows conventions?

Approval Levels:

• Approve - Ready to merge
• Approve with suggestions - Can merge, but consider improvements
• Request changes - Must fix before merge (security/bugs only)

Git Workflow

Branch Naming

feature/add-user-dashboard
fix/checkout-validation-error
hotfix/security-patch-v1.2.1
release/v2.0.0

Commit Messages

# Format
type(scope): brief description

# Examples
feat(checkout): add express payment option
fix(cart): resolve quantity update on mobile
docs(readme): update installation steps
refactor(api): simplify error response handling

PR Workflow

1. Create feature branch from main
2. Make changes with atomic commits
3. Push and create PR
4. Request review from at least 1 teammate
5. Address feedback
6. Squash and merge when approved

Documentation Standards

Code Comments

<?php
// Single line for brief notes.

/*
 * Multi-line for longer explanations.
 * Especially useful for complex logic.
 */

/**
 * DocBlocks for functions, classes, and methods.
 * These appear in IDE tooltips and generated docs.
 */

README Template

# Plugin/Theme Name

Brief description of what this does.

## Requirements

- WordPress 6.0+
- PHP 8.0+
- [Any dependencies]

## Installation

1. Step one
2. Step two
3. Step three

## Configuration

How to configure after installation.

## Usage

Common use cases with examples.

## Hooks Reference

### Actions
- `prefix_action_name` - When it fires, what it's for

### Filters
- `prefix_filter_name` - What it filters, expected return

## Changelog

### 1.0.0
- Initial release

## Support

How to get help.

Communication Guidelines

In Code Reviews

Asking for Changes:

"Hey! This looks great overall. I noticed the SQL query on line 45 might benefit from $wpdb->prepare() for security. Would you mind updating that? Happy to help if you'd like to pair on it!"

Suggesting Improvements:

"Nice work on this feature! One thought - we could potentially use wp_cache_get() here to avoid repeated database calls. What do you think? Not blocking, just an idea for future optimization."

Approving:

"Looks great! Clean code and well-documented. Approved! 🎉"

In Documentation

• Use "you" to address the reader directly
• Use "we" when referring to the team/product
• Keep sentences short and scannable
• Include examples for complex features
• Add helpful tips with friendly icons (💡, ✅, ⚠️)

With Clients

• Lead with solutions, not problems
• Explain technical concepts in plain language
• Set clear expectations with timelines
• Celebrate wins and milestones together

Quick Reference Cards

Security Quick Check

✅ Sanitize: sanitize_text_field(), absint(), sanitize_email()
✅ Escape: esc_html(), esc_attr(), esc_url(), wp_kses_post()
✅ Validate: is_email(), wp_verify_nonce(), current_user_can()
✅ Prepare: $wpdb->prepare() for all SQL with variables

Performance Quick Check

✅ Use transients/cache for expensive operations
✅ Limit queries with posts_per_page (never -1 on frontend)
✅ Use no_found_rows => true when not paginating
✅ Lazy load images and defer non-critical JS
✅ Conditionally enqueue assets only where needed

Accessibility Quick Check

✅ All images have alt text
✅ Form inputs have labels
✅ Color contrast meets WCAG AA
✅ Keyboard navigation works
✅ Skip link present in themes