Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Are there any common practises for commenting the regular expressions: inline comments referring different part of RegEx or general comment for all expression?

share|improve this question
2  
There are but you need to be more specific. For example Bash supports inline comments and Python offers verbose regular expressions. –  faif Dec 5 '12 at 12:19
6  
My rule of thumb for regular expressions is: if you need to comment the regular expression, it's too complicated. –  zzzzBov Dec 5 '12 at 15:43
add comment

This question has an open bounty worth +100 reputation from m0nhawk ending in 5 days.

This question has not received enough attention.

4 Answers

up vote 6 down vote accepted

In my view, a good practice is to concisely state in comments what the general idea of the regular expression is. This saves other developers (or sometimes yourself) the hassle of copy-pasting the regex in a parser like RegExr, only to understand what it does.

share|improve this answer
1  
RegExr will happen anyway, unless the dev is a regex savant. But I agree with providing a general description; that's what I do with my regexes. –  Robert Harvey Dec 5 '12 at 16:22
1  
+1: Anything more detailed will end up being a crash course in regex as a comment. –  Matt Dec 5 '12 at 19:11
    
This answer and the @zzzzBov comments make sense. –  m0nhawk Dec 8 '12 at 12:44
add comment

Typically, I will write a regex and not explain the individual pieces of the regex, but rather what it's purpose is. That is that what and why. This is a bit like asking "What should my comments look like?" to which one would say "Don't write what the code is doing, write why the code is doing what it does"

// Strip the leading "?" and remove the query parameters "offset=<integer>" & "count=<integer> so we have a pattern of the request"          
var search = location.search.substring(1).replace(/offset=[0-9]+?&/g, "").replace(/count=[0-9]+?&/g, "");

Unless you are trying to teach someone about regexes via comments in code, I don't think explaining what each individual piece will do. When working with other programmers, you can safely assume that one would know something as global regular expressions.

share|improve this answer
2  
you would be surprised... –  Matt Dec 5 '12 at 18:55
add comment

I guess it really depends on how you're putting the regex together. Generally speaking I think it would be a bad idea to put comments within the actual regex string itself (not possible in most scenarios, as far as I know). If you really need to comment specific portions of a regular expression (are you trying to teach someone?), then break each chunk into separate strings on their own lines, and comment each line using the normal commenting process for your programming language. Otherwise, pleinolijf's answer is pretty good.

example:

string myregex = "\s" // Match any whitespace once
+ "\n"  // Match one newline character
+ "[a-zA-Z]";  // Match any letter
share|improve this answer
add comment

This is somewhat a language specific answer, but no language is stated in the question.

The book "Dive Into Python" suggests implementing comments using Verbose Regular Expressions:

Python allows you to do this with something called verbose regular expressions. A verbose regular expression is different from a compact regular expression in two ways:

  • Whitespace is ignored. Spaces, tabs, and carriage returns are not matched as spaces, tabs, and carriage returns. They're not matched at all. (If you want to match a space in a verbose regular expression, you'll need to escape it by putting a backslash in front of it.)
  • Comments are ignored. A comment in a verbose regular expression is just like a comment in Python code: it starts with a # character and goes until the end of the line. In this case it's a comment within a multi-line string instead of within your source code, but it works the same way.

Example:

>>> pattern = """
^                   # beginning of string
M{0,4}              # thousands - 0 to 4 M's
(CM|CD|D?C{0,3})    # hundreds - 900 (CM), 400 (CD), 0-300 (0 to 3 C's),
                    #            or 500-800 (D, followed by 0 to 3 C's)
(XC|XL|L?X{0,3})    # tens - 90 (XC), 40 (XL), 0-30 (0 to 3 X's),
                    #        or 50-80 (L, followed by 0 to 3 X's)
(IX|IV|V?I{0,3})    # ones - 9 (IX), 4 (IV), 0-3 (0 to 3 I's),
                    #        or 5-8 (V, followed by 0 to 3 I's)
$                   # end of string
"""
>>> re.search(pattern, 'M', re.VERBOSE)                1

Source and further details here

This method has a slight disadvantage that the caller must know that the pattern is written in a verbose format and call it accordingly.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.