Decide on guidelines for regex formatting

I think an awful lot depends on the text that's being matched in the regex -- whether HTML or PHP or something else.

As far as regex syntax goes, personally I like:

- putting the regex outer characters on lines alone, so they're apart from the rest of the thing
- splitting up brackets onto multiple lines, whether they're capturing, noncapturing, or assertions, with the alternation character on its own line (otherwise it feels quite noisy, like it's participating in the thing being matched, and keeping regex syntax apart from actual content is a key goal IMO)
- chunks of actual content alone on lines where feasible

$regex = '[
  foo
  (?=
    bar
    |
    biz
  )
  kha+n # though putting whitespace inside this feels weird
]';

We don't put operators on their own lines when splitting up if() or large arithmetic statements. We don't put commas on their own lines when splitting up arrays. So to me, having a line with just one operator or paren on it:

|
(?=
)

is weird, wastes a lot of space, takes a longer time to scan, etc. than a somewhat more compact format.

Also, see http://drupal.org/coding-standards#linelength also for our general guidelines on splitting up lines. Maybe the guideline here should be similar to what's suggested for if() statement conditions -- assign sub-expressions to variables with intuitive names and concatenate them together? That would probably be more readable, use less space than the proposal above, and be self-documenting and more in line with our other coding standards. Something like this maybe:

$match_this = '|...|';
$match_that = '|...|';
$match = "($match_this|$match_that)";

I think the pipes in regexes are quite different from commas; they detract significantly from the content if on the same line.

> assign sub-expressions to variables with intuitive names and concatenate them together

Could be a useful tactic. But on the other hand, it can make it harder to see how the regex is working. The example you posted is already broken, for instance ;)

The thing to bear in mind is that regexes are complex beasts and they are pretty much a separate programming language.

It was not meant to be a valid example, just an idea. :)

Here's more on what I mean by the content of the regex affecting what sort of layout makes sense. In module builder I need to capture portions of the function docblock, the declaration, and the function body. I've laid it out so it more or less matches how the docblock and function are laid out in PHP:

  // The pattern for extracting function data: capture first line of doc,
  // function declaration, and hook name.
  $pattern = '[
           / \* \* \n     # start phpdoc
          \  \* \  ( .* ) \n  # first line of phpdoc: capture the text
      (?: \  \* .* \n )*  # lines of phpdoc
          \  \* /  \n     # end phpdoc
         ( function \ ( hook_\w* ) .* ) \  { # function declaration: capture both entire declaration and name
     ( (?: .* \n )*? )    # function body
         ^ }
  ]mx';  

Coding standards changes are now part of the TWG

Moving this issue to the Coding Standards queue per the new workflow defined in #2428153: Create and document a process for updating coding standards.

This was discussed at #3456119: Coding Standards Meeting Tuesday 2024-06-18 2100 UTC. We are considering adding something for this but have not settled on any details or where this information would go. So far adding something like, "All regexes with more than one group must have a comment' has been suggested. But that does cover how to make a long regex multi-line. Perhaps just adding an example it the best option here.

I have added the new issue summary template.