What I need is a command-line tool to do some basic PDF preflighting (eg. non-CMYK elements, non-embedded fonts, images below 300dpi, characters which may cause difficulties in printing, etc.). Is that so much to ask? When the PDF spec is 1300 pages long, it is. Still, don’t think I won’t try and take a stab at it.

Let’s ignore that not everyone has Microsoft Excel on their machines. (I don’t and instead had to wait for that ugly behemoth, NeoOffice, to sputter to life and display the data.) Let’s also ignore that if a spreadsheet was the answer, it could have been released in CSV format. Instead, let’s look at the data. (Those of you without Microsoft Excel will have to follow along using the image below.)

The open letter to Adam Giambrone describes the spreadsheet as “easy to use”. When you say something is easy to use, it had damn well better be. Personally, I had to stare at the spreadsheet for a few minutes before I could make heads or tails of it. Describing something as easy to use when it isn’t has the adverse effect of making anyone who doesn’t find it intuitive feel like an idiot.

First, the data is not a table and the first column seems to have absolutely no relation to the matching rows in the other columns. I have no idea what that first column is supposed to represent. Is it the cities from which the comments originated? Who knows.

Second, the acronyms and numbers you see (SPC 3, RT 4, etc.) are supposed to describe the website and comment number which made the suggestion in that column. There’s no legend, so I can only assume that “TI” means Torontoist.com and “RT” means Reading Toronto, “SPC” means Spacing and “BT” means blogTO. No website addresses or comment URLs are given so when this spreadsheet is printed or passed around the internals of the TTC, nobody will know what the heck those letters and numbers mean and won’t know where to go for more information.

Third, the spreadsheet isn’t even using spreadsheet functionality. It’s a table, but it’s not. The comment references are comma-separated across multiple rows, so there’s no way to do anything meaningful with this data such as sum the columns and graph the results, which is what everyone wants to do with spreadsheets. To find comment totals, you will have to manually count the references.

Fourth, you can’t see it from the image but my website is misspelled in row 22. It’s crazedmonkey.com, not crazymonkey.com. Thanks, guys.

Fifth, many of the comments referenced do not match the feature under which they appear (eg. TI 23 under the independent server suggestion). Also, RT 14 does not exist.

How would I have captured the website findings? First, I wouldn’t have made the mistake to release it in spreadsheet form. Instead, a simple HTML page would do the trick. The data can be expressed as a list using CSS styling wherever appropriate:

<ol>
  <li>Suggestion 1
    <ul>
      <li><a href="link to comment">website and comment author or number</a></li>
      …
    </ul>
  </li>
  …
</ol>

With the above format, every comment has a link to check. The file or link can still be passed around with no loss of information.

All of this begs the question, why even bother with a findings document at all? The comments are in an open forum which everyone can read and from which they can draw their own conclusions. Releasing a difficult to understand requirements document does nothing to help, but actually serves to inhibit. Who is going to take seriously anyone who creates a spreadsheet like that and passes it off as helpful? It’s well-intentioned but there’s a reason why the requirements gathering process, particularly in the software and usability fields, is left to the experts, or at least those with domain experience.

Update: I have since remixed the suggestion matrix into a HTML page as described above.

My image tiler uses Free Software, is released under the GPL, and has the following features:

• Tiles most image formats, including GIF, JPEG, PNG and TIFF.
• Works on most flavours of Unix, including Mac OS X.
• Supports version 1 and version 2 zoom levels.
• Automatically calculates offsets for all zoom levels.
• Supports padding from the upper-left as output by the web-based tiling helper.
• Automatically pads image to size appropriate to Google Maps (ie. multiple of 256).
• Optionally discards empty transparent tiles to save space.
• Optional prefix for each tile.
• Outputs tiles in PNG format.
• Compresses tiles with either advpng or pngcrush.

The tiler requires ImageMagick and advpng or pngcrush for PNG compression. (I recommend advpng as it is faster and compresses smaller in most situations.) Tiled image size is restricted only by disk space and ImageMagick limitations.

To use the tile cutter, one need only specify the image being tiled, the Google tile coordinates of the top-left tile, the zoom level for which those coordinates are valid and the zoom level the tile represents. For example, suppose we have three images (img15.png, img16.png and img17.png) for zoom levels 15 through 17 (in version 2 zoom levels), respectively. The top-left corner of the image at level 15 is 1812,1924. You would then run the following commands to generate the tiles:

% googletilecutter -o 15 -t 1812,1924 -z 15 img15.png
% googletilecutter -o 15 -t 1812,1924 -z 16 img16.png
% googletilecutter -o 15 -t 1812,1924 -z 17 img17.png

Note that the only options which need to be changed from image to image are the zoom level of the image and the image itself. Compression and discarding of empty tiles is performed automatically. For more command-line options execute the script with the -h option.

Download the Unix command-line tile cutter for Google Maps. If you have any problems or experience any unexpected behaviour, please leave a comment below.

if foo = 1 or bar = 3 or abc = 4 then
    print Hello World
end if

You can do boolean OR in BASH by using the -o operator. The following is the above code written in BASH:

if [ $foo -eq 1 -o $bar -eq 3 -o $abc -eq 4 ]; then
    echo Hello World
fi

For boolean AND, use the -a operator. You can also intermix the two.

• Writing monolithic tests. More often than not, I see people writing one test method for each method they are testing with all their asserts contained within that test method. While not incorrect, this will impede testing as most test suites stop at the first failed assert. For example, if a test method has ten asserts and the first one fails, no conclusion can be immediately made regarding the remaining nine asserts. As a result, the first failure must be fixed before the remaining nine can be tested. This is particularly frustrating when tests are automated and run on a regular basis. Consider splitting your tests by requirement and including no more than the minimum asserts necessary inside a test method to test the associated requirement.
• Not running the tests on a regular basis or altering them as requirements change. Once tests are written and they pass, many developers do not run those tests again. Months later, changes in requirements and code lead to a drift between the tests and what they are testing. Should someone run the tests again, the tested code will appear to be incorrect and confusion will result. As such, it is important to run tests on a frequent basis, ideally automatically, and to keep tests in line with requirements.
• Improper description of what test cases are testing. Unit tests cannot exist in a vacuum. Mislabelled or undescribed tests only serve to confuse which requirements they are testing. Sometimes asserts are self-explanatory but more often they are not and require further output to describe failures. Consider naming your test methods to describe what they are testing (eg. testThatMethodFooResultsInCondition) and/or include a written explanation inside the assert statement to be printed alongside the failure.
• Noisy test output. Depending on the testing library you are using, your tests may already be generating needless output. Adding more output will only result in confusing test results. Positive test results should never output data to the test log. Negative test results should make use of the output facilities within the testing framework for uniform formatting.
• Improper use of the test case API. This is a small detail but deserves to be mentioned. I have seen many test cases which do not make good use of the testing framework under which they are running, leading to unhelpful output. For instance, in JUnit assertTrue(foo == 3) is not equivalent to assertEquals(3, foo). The former will output a generic failure message while the latter will explicitly output the expected and actual results. Pay careful attention to the test framework’s assert method signatures as order will often matter. For instance, in JUnit, assertEquals(3, foo) is not equivalent to assertEquals(foo, 3) and will result in two different failure messages.

<div id="map">
<script src="http://crazedmonkey.com/ttcgooglemap/ttcgooglemaps.js"
type="text/javascript"></script>
<script type="text/javascript">
<!--
    var map = new GMap( document.getElementById( "map" ) );
    map.addControl( new GSmallMapControl() );
    map.centerAndZoom( new GPoint( -79.386871, 43.660241 ), 4 );

    // Add your own markers and polylines here.

    drawTtcSubwayMap( map );
-->
</script>

There are two other additional functions, drawTtcSubwayMapColor() and writeTtcSubwayStations(), which can be used to specify the colors for the different subway lines and to display the colour-coded list in a div, respectively. I might add more helper methods later if there is a demand for them.

You can affect how the stations appear in the info pop-up by styling div elements of the station class.

Originally I had thought to limit access to my Javascript file to those who asked permission to use it. Doing so would make me aware of how people were using the map. For now, people are free to link the Javascript in their pages. All I ask is that you leave a comment on my weblog with a link to your page, and include the following HTML somewhere near the map:

<p>TTC station code and coordinates provided by
<a href="http://crazedmonkey.com/">Ian Stevens</a> and his
<a href="http://crazedmonkey.com/ttcgooglemap/">TTC Subway Google Map</a>.</p>

Linking, not copying, the script has its advantages, namely that any changes or additions that I make will propagate to your map. There are also a few known bugs, all of which have to do with Internet Explorer, that I hope to address soon.

Translating the subway station addresses into GPoint objects was a little difficult given that there appears to be no free geocoding service for Canadian addresses. However, Google Maps can work as a geocoder, albeit a somewhat slow one, sometimes taking several seconds to produce a result. If you have access to a Unix command-line, you can make use of the following script:

#!/bin/sh
wget -q -O- http://maps.google.com?q=\\
`echo $1 | tr " " "+"` | sed -n -e \\
"s/.*<point lat=\"\\([^\"]*\\)\" lng=\"\\([^\"]*\\)\".*/new GPoint( \\2, \\1 )/p"

If I have one beef with the API, it’s with the GIcon class and the requirement to set the icon shadow, the icon and shadow sizes and the anchor point. A shadow should not be required and image sizes can be inferred. However, the icon will not display if any of these properties are not set.

Update: I have since added a clickable list of subway stations to the map.

Update: Now any Google Map can contain the TTC subway map.

Too often it would seem that project managers and developers forget the old maxim that “time is money.” Projects are often started without a proper plan including a time estimate, cost assessment and an analysis of whether the benefits outweigh those costs. This mismanagement of time results in changes of scope over the course of the project with creeping time overruns as “unforeseen” difficulties arise and features are tacked on.

Sadly, the Toronto Police eCOPS failure isn’t an anomaly in the software industry. The only news here is that it has been a colossal waste of public money.