Regex is conceptually incredibly easy to understand.

But regex is also syntactically designed by Satan himself.

Most programming languages use commands that are semantically understandable, like "for" and "let" and "return" and mostly symbols we already know like "+" and "=". They use newlines and indentation for organization. And they put multiple commands on multiple lines and you can add comments and everything.

Regex is exclusively punctuation, with its own idiosyncratic meanings, all compressed into a single line, zero organization, zero comments, and impossible to remember what each symbol does if you don't use it daily. Not to mention the nightmare of escaping regexes when expressed as strings, on top of escaping regex symbols within the regex itself.

I swear it's high time we come up with a regex replacement that looks like normal Python code or HTML or something. So instead of:

  ^(\+\d{1,3}-?)?\d{3}-\d{3}-\d{4}$

  <start>
    <optional>  # Optional country code
      "+"
      <digit>[1-3]
      "-"
    </optional>
    <digit>[3]  # Area code
    "-"
    <digit>[3]
    "-"
    <digit>[4]
  <end>

What you want is something akin to a Raku (perl6) grammar, which was their enhancement to matching they developed to go beyond regular expressions.

    grammar IniFile {
        token key   { \w+ }
        token value { <-[\n;]>+ }
        token pair  { <key> \h* '=' \h* <value> \n+ }
        token TOP   { <pair>+ }
    }

    my $text = "user = alice\nrole = admin\n";
    my $match = IniFile.parse($text);

    if $match {
        say "Parsed successfully!";
    }

If you're not looking for that, and more specifically what you have shown above, there are often ways to accomplish that in certain languages. In Perl it's easy because you can use regex cars in a regex, so you can just assign `my $digit = qr/(? :0-9)/;` and then use it in the regex as you did (and Perl already supports non matching whitespace with a flag). For that matter, Perl regexes allow you to define chunks purely within the regex to be reused in a DEFINE block, so possibly that is a feature other regex engines have as well.

In practice, including a unit test for any nontrivial regex in your application is very helpful. You can demonstrate which sorts of strings are expected to match and, maybe more importantly, which ones are not expected to match. The same goes for testing the capture group contents.

It may feel silly to have a whole unit test for a one-line regex, but that one line can be really dense. If you wrote a function to parse the string without regex, that function would be complex enough to warrant a unit test, after all.

Introducing regressions when tweaking a regex in your application is also a big risk which unit tests can help mitigate.

If you want readability you can write

    ^(?P<country_code>\+[0-9]{1,3}-?)?[0-9]{3}-[0-9]{3}-[0-9]{4}$

  ^
  (   
      \+
      [0-9]{1,3}
      -?
  )?   # optional country code
  [0-9]{3}
  -
  [0-9]{3}
  -
  [0-9]{4}
  $

Regex in xml? Now you have 2 problems. And the comments are not xml comments even.

Ultimately it is a dsl. Should equations in math also use full words and comments?

No, they should not. Maybe a nice syntax for grammars like raku is a better approach.

There are certainly alternatives, like https://pomsky-lang.org/

Most regex dialects allow whitespace and comments, so that already gets you halfway there.

wouldn't it be easier to just add a comment block in the code above the regex?

You can enable extended mode for most engines, which allows you to add white space and comments.

Personally, I like regexes, in the same way that I like shell string manipulation: it looks utterly inscrutable, and performs magic. If I write one in code meant for others, I usually use extended mode with each line commented.

I think some languages do have a library-style version of regex. But the function names aren't consistent between the different libraries. Maybe then we need to put on special goggles to make them look the same.