Clarify scope of PHP coding standards for core (major version) and contrib code

Posted by sun on October 1, 2011 at 8:09pm:

Problem

• Uncertainty about when or how to apply coding standards across Drupal core versions and core vs. contrib code.

Goal

• Clarify the scope of coding standards with regard to:

  1. major versions of core
  2. core vs. contrib code

• Explicitly specify/state which particular coding standards have been different for earlier versions.

Details

• In #1290258-59 some (legit) confusion arose around my statement in a contribissue:

  Drupal coding standards are version-independent and "always-current". All new code should follow the current standards, regardless of (core) version. Existing code in older versions may be updated, but doesn't necessarily have to be. Especially for larger code-bases (like Drupal core), updating the code of a previous version for current standards may too huge of a task. However, code in current versions should follow the current standards. Lastly, when following this practice, make sure to not squeeze coding standards updates/clean-ups into otherwise unrelated patches.

• Based on that, the main people caring for Drupal coding standards discussed it and added the following intro text to http://drupal.org/coding-standards:

  Drupal coding standards are version-independent and "always-current". All new code should follow the current standards, regardless of (core) version. Existing code in older versions may be updated, but doesn't necessarily have to be. Especially for larger code-bases (like Drupal core), updating the code of a previous version for the current standards may too huge of a task. However, code in current versions should follow the current standards.

  Note: Do not squeeze coding standards updates/clean-ups into otherwise unrelated patches. Only touch code lines that are actually relevant. To update existing code for the current standards, always create separate and dedicated issues and patches.

  Based on the confusion that arose in aforementioned issue, this could have probably been discussed some more. ;)

• As determined in aforementioned issue, there are coding standards - e.g., for string concatenation - which we currently apply differently for Drupal core patches depending on the core version a patch is for.

  I.e., patches backported from D7 to D6 may be adjusted for the differing string concatenation rules being used throughout Drupal 6 core for consistency.

  (Note, however, that I (sun) am currently not sure whether this "should" is actually turned into a "required" for backported D6 patches.)

• The above coding standards intro text was primarily intended to clarify the scope of current coding standards in contributed extensions, and also clarify how to update (or ignore) existing code.

Proposed resolutions (and their drawbacks)

Require all code to meet version-specific standards.

We have no currently-published version-specific standards, and no easy way to produce them.

Require all code to be consistent with the surrounding code, regardless of standards.

The surrounding code, despite huge efforts at standardization, often lacks consistency.

Require all code to meet currently-published standards, regardless of surrounding code.

This introduces inconsistencies which standards are written to avoid.

Require all code to pass coder review as written for the target branch of core.

Coder review needs more active maintainers before this option can be considered.

Use a common-sense approach.

Even people who have "common sense" often disagree on what it means.

Discuss at http://drupal.org/node/1296842.