How I Code On This Blog: Elegance Vs. Transparency

My recent comment exchange with Scriptar has prodded me to post an explanation of how I code on this blog.

I view the code I post here as having two priorities: elegance and transparency, weighted slightly more toward elegance.

What I mean is that most importantly, the code I post should be as simple, compact and direct as possible. It should solve the problem with as few lines of code as possible, using as direct an approach to solving the problem as possible, and without introducing any additional steps or problems that need to be resolved.

For example, suppose I want to demonstrate how, in PHP, to concatenate an array into a string. I could do this:

$val = array('here', 'there', 'everywhere');
$out = "The words in the array are ";
foreach($val as $item) {
	$out .= "$item, ";
$out = substr($out, 0, (strlen($out) - 2)) . ".";
echo $out;

But I’d almost always write the solution thus:

$val = array('here', 'there', 'everywhere');
echo "The words in the array are " . implode(", ", $val) . ".";

That is, I’d write it as the second example — since it’s far more elegant — unless doing it that way either removed the ability to make an important point about the way things work, or obfuscates some consideration that ought to be made plain.

Sometimes, The Long Way Is The Better Way

A perfect example of this is the PHP code I show in my blog post about finding nearby geocoded ZIP Codes.

Look at this block of code from that post:

$lat1 = $row['latitude'];
$lon1 = $row['longitude'];
$d = $_POST['distance'];
//earth's radius in miles
$r = 3959;

$latN = rad2deg(asin(sin(deg2rad($lat1)) * cos($d / $r) + cos(deg2rad($lat1)) * sin($d / $r) * cos(deg2rad(0))));
$latS = rad2deg(asin(sin(deg2rad($lat1)) * cos($d / $r) + cos(deg2rad($lat1)) * sin($d / $r) * cos(deg2rad(180))));
$lonE = rad2deg(deg2rad($lon1) + atan2(sin(deg2rad(90)) * sin($d / $r) * cos(deg2rad($lat1)), cos($d / $r) - sin(deg2rad($lat1)) * sin(deg2rad($latN))));
$lonW = rad2deg(deg2rad($lon1) + atan2(sin(deg2rad(270)) * sin($d / $r) * cos(deg2rad($lat1)), cos($d / $r) - sin(deg2rad($lat1)) * sin(deg2rad($latN))));

A far more elegant way to write the same thing is this:

$lat1 = deg2rad($row['latitude']);
$lon1 = deg2rad($row['longitude']);
$d = $_POST['distance'];
//earth's radius in miles
$r = 3959;

$tmp1 = sin($lat1) * cos($d / $r) + cos($lat1) * sin($d / $r);
$latN = rad2deg(asin($tmp1));
$latS = rad2deg(asin($tmp1 * -1));
$tmp2 = sin($d / $r) * cos($lat1);
$tmp3 = cos($d / $r) - sin($lat1) * sin(deg2rad($latN));
$lonE = rad2deg($lon1 + atan2($tmp2, $tmp3));
$lonW = rad2deg($lon1 + atan2($tmp2 * -1, $tmp3));

By converting the database values I retrieve to radians before I work with them, condensing repetitive calculations to single variables, removing explicit conversions of fixed bearing calculations that will become -1 in the formulas and eliminating needless multiplications when those bearing calculations will be 1, the second example is far more concise.

However, it does not easily compare to the formula I noted I would use to calculate the coordinates. In this case, using more explicit, more verbose code better equates the problem to its solution, and I want users to easily equate the solutions I provide to the problems at hand.

Sometimes, Half Truths Are Better Than Whole Truths

Also, as a rule I try to be as accurate in terminology as I can be, without obfuscating the point beyond recognition. I don’t want to so bog down the discussion with arcana, multiple approaches, special considerations and exceptions to the rule, so that the reader winds up more confused and desperate than when he started.

I try to point out when I am speaking in general terms and I try to break out, into asides, extended conversations that might serve to confuse the point. But in some cases, I believe that adding additional information that makes a point 100 percent correct will not profit a beginning programmer, so I either exclude it or post a warning that the discussion / code I am providing will not work in certain circumstances.

Again, my overriding concern is to provide good code, but I want the people reading these posts to understand why and how the code works, so that they can amend it to fit their needs. Sometimes, that means engaging in generalities and taking a longer, less efficient route to some end.

Sometimes, I Just Screw Up

And, in all honesty, sometimes I turn out a turkey. I’m learning all the time, too, and I make rookie mistakes, fail to test what I wrote or lose the forest through the trees, just like everyone else. So sometimes, I actually mean a solution to be elegant, but my own limitations prevent it.

I occasionally review old postings and clean up wasteful code. But this blog has over 200 posts spanning three years, and I’ve not reviewed them all. You will find some posts, especially older ones, that aren’t up to snuff. If you see such a post, you’d be a huge help by posting a comment and either suggesting better code or asking me to clean it up.

1 Comment

Leave a Reply

  • Check out the Commenting Guidelines before commenting, please!
  • Want to share code? Please put it into a GitHub Gist, CodePen or pastebin and link to that in your comment.
  • Just have a line or two of markup? Wrap them in an appropriate SyntaxHighlighter Evolved shortcode for your programming language, please!