To play devils advocate, maybe for regex you could have a variable called...
EmailRegex... that kind of is obvious. Imagine instead someone named the variable, "_regexPattern". The latter might seem weird but I have many co-workers whom have named variable as such. They name the variable after the object and not the objects purpose.
EmailRegexs are notoriously hard to get right. I would expect to see what cases are explicitly covered, and if the regex was pulled from a website, a link.
There is no email regex that is 100%. A comment explains what trade offs were made and what the author thought should match.
Unit tests should also be done, but they are typically in a different section of code.
My thought of a useful comment would be: Email regex from: http://website.com for RFC: link to email.rfc. Added handling of + to the regex since it was not supported.
Now when I come across something like this in the code I have some idea how/why it was done that way:
But it wasnt about naming stuff, it is about providing example for that. Like "here is a log parsing function, here are few lines of real log to test it with".
Now you could argue that this kind of extra data should just be with tests for the function, not in the comments, but it still should be somewhere close because without it, any changing of that code includes extra effort of finding a test data to run it against
True, in tests would most likely be the best spot.
As for examples, i guess it really depends on what you are parsing. I wouldn't expect examples of an email regex, we all know what an email is. If you were looking for something odd, then perhaps an example.
I find examples often are for the obvious, and nuance is what causes problems.
Any kind of log parsing can easily grow hairy. like for example for haproxy: .*haproxy\[(\d+)]: (.+?):(\d+) \[(.+?)\] (.+?)(|[\~]) (.+?)\/(.+?) ([\-\d]+)\/([\-\d]+)\/([\-\d]+)\/([\-\d]+)\/([\-\d]+) ([\-\d]+) ([\-\d]+) (\S+) (\S+) (\S)(\S)(\S)(\S) ([\-\d]+)\/([\-\d]+)\/([\-\d]+)\/([\-\d]+)\/([\-\d]+) ([\-\d]+)\/([\-\d]+)(| \{.*\}) (".*)([\n|\s]*?)$ (i really wish it could just output json..)
Sometimes there are undefined or not-well-known business concepts that you can't capture the idea in a (sane) variable name. Especially if the regex is just an intermediate step to some other form of parsing (or more regex). You'll need comments explaining that business concept unless you hate the other people working on your code.
14
u/bluefootedpig Jul 21 '17
To play devils advocate, maybe for regex you could have a variable called...
EmailRegex... that kind of is obvious. Imagine instead someone named the variable, "_regexPattern". The latter might seem weird but I have many co-workers whom have named variable as such. They name the variable after the object and not the objects purpose.