Welcome to End Point’s blog

Ongoing observations by End Point people

Make your code search-friendly

Here's something about coding style that you may not have considered: is your code "search-friendly"? That is, does the format of your code help or hinder someone who might be searching it for context while debugging, extending, or just learning how it works?

Seriously Contrived Example (from Perl):

my $string = q{Your transaction could not be} .
   q{ processed due to a charge} .
   q{ card error.};
return $string;

Now someone's going to experience this error and wonder where it occurs. So armed with grep, or ack, or git-grep, they set off into the wilderness:

$ git grep 'could not be processed'
$ git grep 'charge card error'
$ git grep -e 'transaction.*charge.*error'
$ alsdkjgalkghkf

(The last simulates pounding the keyboard with both fists.) I would suggest humbly that "strings you emit as a line should appear as a line in your code", if for no other reason than that it makes it so much easier for you or others to find them. Thus:

my $string = <<'MSG';
Your transaction could not be processed due to a charge card error.
return $string;

1 comment:

Jeff Boes said...

I'm revisiting this because another, cringe-worthy example has tripped me up:

my $_group_class = 'Corp::M::Client::Group';
my $_group_type_class = $_group_class . '::Type';

and so on. The idea here is "DRY" (don't repeat yourself), but the drawback is that when you're searching the code for instances of:


you are doomed to disappointment. (Especially in the case where the code doesn't "use" the module directly.)