WordPress / WordPress/WordPress-Coding-Standards

Proposal: formalize database table and field name naming conventions

Open
#1,764 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Component: Core Type: Enhancement
Dominant language
PHP
Stars
2.8k
Forks
521
Avg merge
5d 20h
Merged PRs (30d)
1

Description

Is your feature request related to a problem?

The WP Coding Standards handbook currently covers naming conventions for all sorts of structures, but does not formalize any naming conventions for database tables, nor table fields/columns.

As case-sensitive names can cause issues with cross-platform compatibility, the unofficial guideline is to always use lowercase names with words underscore separated.

This unofficial convention is largely complied with within WP core at the moment, with some notable exceptions, such as the comment_ID, comment_post_ID and comment_author_IP fields in the comments table, ID in the posts and users tables and ID and IP in the multisite registration_log tables.

Based on a brief discussion about this in the #core-coding-standards Slack channel, we are proposing to formalize this naming convention and add a rule to that effect to the handbook.

Describe the solution you'd like

If this proposal is accepted and a rule to this effect added to the handbook, a sniff can be written which would examine any CREATE TABLE and ALTER TABLE database queries to verify that table names and field names comply with this requirement.

I'm proposing that existing exceptions in Core as listed above will not be changed as the BC-break would be too large.

Additional context (optional)

  • Some research will need to be done to see if there are any other MySQL queries which would need to be examined by the sniff.
  • If table names or field names are passed into the query using variables of constants, the sniff will not be able to determine the actual name.
    Table names based on $wpdb, such as $wpdb->terms can be ignored by the sniff.
    For any other variables/constants, we will need to decide whether to err on the side of caution and throw a warning which will often turn out to be a false positive or to err on avoiding annoyance, which may lead to false negatives.

/cc @pento @Ipstenu

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked WP Coding Standards handbook naming-conventions section and the referenced Slack discussion. Research MySQL CREATE TABLE and ALTER TABLE queries, including names supplied through variables or constants, to define the sniff's scope and exceptions. Done means the convention, existing Core exceptions, and dynamic-name handling are agreed and the handbook rule is updated.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.