Tips

General comments to be written


Coder's Crib SheetTop

Problem. You are usually focused on the big picture and the logic you are implementing. You end up wasting time finding and fixing compiler errors -- nitty gritty mistakes in command syntax and the like. It's typically worse if you have been away from coding for weeks or months, or if you are working with more than one language on a project.

Solution. The Crib Sheet is designed for lookup of command syntax within 5 seconds. A little test driving is useful to gain sufficient familiarity with the Crib Sheet to find a command or topic quickly.

Tips

  • Select all the languages you are working with before clicking to load the appropriate Crib Sheet. (Yes, there are 7 separate sheets -- covering all combinations of the 3 languages.)
  • To find a command, first click on its category under Contents. Then click on its name in the left-hand menu.
  • Corollary: use the Top buttons at the right to return to the Contents list.
  • Notation: all variables begin with a "$" (aside from required special notation in Perl for arrays and hashes).
  • Operators like "and" and "or" are under Control ops/Logical.
  • Skim the drop-down list under Index (top of the page) to gain familiarity with the terms in it. It's the quickest way, for example, to find "Here documents."
  • "Regexp" is short for regular expression, but then you already knew that. :-)


Naming Conventions for VariablesTop

Problem. You don't know (or remember) the data type of a variable. Not knowing which commands are applicable to the variable leads to coding errors. Perhaps the variable's name doesn't make it clear and no nearby comment is helpful. You are working in one of the loosely structured languages I feature on this website, so you have no data definition to refer to, unlike in C or Java. While I can usually tell a string from a number, and rarely need to differentiate which type of number (integer or floating point) a numerical variable is, less common data types pose challenges to rapid, bug-free coding.

Solution. I use coded prefixes, as listed below.

Data type prefixes

  • a_ -- one-dimensional array
  • h_ -- one-dimensional hash
  • l_ -- list (Perl)
  • o_ -- object
  • s_ -- string (rarely used)

Multi-dimensional examples ... left-most character is the outer dimension

  • aa_ -- 2-D array
  • aaa_ -- 3-D array
  • hh_ -- 2-D hash
  • ha_ -- hash of arrays ... you get the idea

Data source/location prefixes

  • g_ -- global variable
  • f_ -- variable in an HTML form (implies data arrives as a string, even if inherently a number)
  • pm_ -- command line parameter (Perl)

Examples combining data types and source/locations (I write all variables with a leading "$".)

  • $ga_somename -- a global array
  • $fl_somename -- user input from a multi-choice select list in an HTML form


Code Structure Before ContentTop

Problem. Runaway code -- notably unclosed parentheses or curly braces -- cause compiler errors that can be time consuming and frustrating to run down.

Solution. Code the structure first, then back up to fill in content. I typically lay out a structure like the following before filling in any content.

   if ()  {
   
   }
   else ()  {
   
   }

My new text editor, PSPad, is helpful in this regard. When you type the first character of a structural pair -- quotation mark, parenthesis, curly brace, angle bracket (for HTML tag) -- PSPad automatically adds the associated closing character. It can't know, for example, that you intend to add an "else" clause as part of a compound "if" clause.


Advanced CommentsTop

You already understand the basic premise behind taking the time to write comments in your code. When you return to the code later, perhaps years later, comments can be life savers in terms of getting back up to speed.

The tips below are outside-the-box uses for comments you may not have thought of yet.

Tips

  • Reserve block comments -- "/* ... */" in PHP and JavaScript, "=begin ... =cut" in Perl -- for debugging. When tracking down a compilation error, quickly commenting out sizable blocks of code can be a huge time saver. Thus when writing a multi-line comment, simply start each line with "//" ("#" in Perl).
  • If your Web page is a PHP assembly of several small files, use HTML comments to identify each included file. Such comments aid in quickly pinpointing where to install a change on a Web page. Test that concept by doing a View Source on this page.
    Look for the line <!-- start of tips/advanced_comments.html -->, which is the top line in this file,
    and the line <!-- end of tips/advanced_comments.html -->, which ends the file.
  • While the View Source is handy, look down about 30 lines from the top, where you will find today's date. It's generated by residual PHP code bracketed by HTML comments (I used to display the date as part of a standard header.) One could use this technique to leave a hidden time stamp in any Web page.
  • Want a comment that won't appear in a View Source display?
    Use an inline PHP statement: <?php // comment goes here ?>.


Using Quotation Marks WiselyTop

You know, of course, that double quotes are interpolating, whereas single quotes are not. With this principle in mind, I follow two guidelines in my use of quotes.

I use single quotes unless I need double quotes. The benefit is that when I'm skimming my code for possible problems, I can safely ignore all content within single quotes. I don't carry this to extremes however -- preferring "a backslash isn't needed" to 'a backslash isn\'t needed'.

Quotes are essentially clutter, adversely affecting the readability of your code. When a string contains many quotes, notably in multi-line concatenations, a "Here" document is usually preferable. If Here documents (not available in JavaScript) are new to you, by all means befriend them.

PHP:
  $string = <<< SOMENAME
Note triple left angle brackets.
All variables are interpolated, as though this was a double quoted string.
Backslash variable names -- Ex: \$var -- if embedding code snippets in a Here doc.
Include as many lines as you want.
SOMENAME; // starts in col 1. Ends with a semi-colon

Perl:
  $str = << "SOMENAME"; # or 'SOMENAME'; or SOMENAME;
Note double, not triple, left angle brackets.
Note trailing semi-colon on first line.
'SOMENAME' is the non-interpolating version. The other two -- "SOMENAME" and SOMENAME -- are interpolating.
SOMENAME  # starts in col 1. No trailing semi-colon.

Feedback: webmaster@hashes.com