The Boston Diaries

Saturday, January 31, 2015

Some commentary about comments and commit messages

Whoever wrote line 4 of the following code snippet decided to access the clientLeft property of a DOM node for some reason, but do nothing with the result. It’s pretty mysterious. Can you tell why they did it, or is it safe to change or remove that call in the future?

If someone pasted you this code, like I did here, you probably won’t be able to tell who wrote this line, what was their reasoning, and is it necessary to keep it. However, most of the time when working on a project you’ll have access to its history via version control systems.

Via Hacker News, Every line of code is always documented

At work, a former developer would always include a huge comment at the top of each file, describing the history of bug fixes to the code. It looked something like this:

//---------------------------------------------------------------------------
//
// HISTORY OF CHANGE  
//
// -----+--------+------------------------------------------+------+---------
// VERS | DATE   | DESCRIPTION OF CHANGE                    | INIT | PR#
// =====+========+==========================================+======+=========
//  001 |06/09/05| File creation.                           | ABC  | B1017 
// -----+--------+------------------------------------------+------+---------
//  002 |06/24/07| Optimize the fob.                        | XYZ  | B1130
// -----+--------+------------------------------------------+------+---------
//  003 |01/08/08| Make the fob more flexible.              | XYZ  | B0019
// -----+--------+------------------------------------------+------+---------
//  004 |04/15/09| The fob wasn't frobbing the widget.      | XYZ  | B0021
// -----+--------+------------------------------------------+------+---------
//  005 |02/02/10| Reduce the size of the gadget handler.   | XYZ  | B0005
// -----+--------+------------------------------------------+------+---------
//  006 |04/05/10| Work around Whatzat Protocol bug.        | XYZ  | B0024
//      |04/14/10| Generalize the widget protocol.          |      | B0007
// -----+--------+------------------------------------------+------+---------
//  007 |01/20/10| Performance enhancement.                 | XYZ  | B1019
// -----+--------+------------------------------------------+------+---------
//  008 |03/09/11| Race condition between hare and turtle.  | XYZ  | B1019
//      |03/15/11| Beef up authentication.                  |      | B1021
// -----+--------+------------------------------------------+------+---------

Seeing how we already use a version control system, which already contains this information and thus, there is no real need to put this in the source code itself, I asked him about it.

“Because not everyone has access to the version control server,” he said.

“What? Who can see the source code but does not have access to the version control server?” I asked.

“Customers we license the code to,” he said.

“But we don't license the code to anyone,” I said.

He then stormed off, saying I didn't understand how software was developed, but I think I see where he was coming from. He has a side-company where he licenses the source code to his products and didn't want his customers to have access to his version control server. Adding this information to the files themselves let his customers know what has been fixed. But he kept the practice up at The Corporation because that's the way he's always done it. It made sense for his company, but not for The Corporation. We aren't going to license this code to anyone, and anyone that is working on it has access to the version control server and can see the entire history of any of the files in the project.

But that's not to say that all commentary about the code should go exclusively in version control. The history of bug fixes, yes, that can go into version control as there's no need to clutter up the source code files with that information. But comments that describe why the code is doing something odd should go in the file itself, above the odd bit of code.

For example, in my own blogging engine, I have this commit:

commit eab6ecb7149f8b70614657cd20fe09337cf5e977
Author: Sean Conner <spc@conman.org>
Date:   Tue Jan 15 23:43:19 2013 -0500

    Bug fix---tumbler problems, but not necessarily with the parsing
    
    The intent was if the start date was later than the end date, swap the
    two dates and set the reverse flag.  Unfortunately, the logic to
    determine the swap was wrong.  Wong wrong wrong wrong wrong.  I moved
    the check down, and rewrote the check logic.  It should be fine now, but
    get back to me in another decade.

But the code that handles this is a bit odd (it was even worse before I fixed it) so I added a comment to the modified code:

    /*------------------------------------------------------------------------
    ; swap tumblers if required.  If the parts are the default values, swap
    ; them, as they probably weren't specified and need swapping as well.
    ;
    ; Example:
    ;
    ;     2000/02/04    - 01/26
    ;  -> 2000/02/04.1  - 2000/01/26.23
    ;  -> 2000/01/26.23 - 2000/02/04.1
    ;  -> 2000/01/26.1  - 2000/02/04.23
    ;
    ;-----------------------------------------------------------------------*/

    if (btm_cmp(&start,&end) > 0)
    {
      struct btm tmp;

      gd.f.reverse = true;
      tmp   = start;
      start = end;
      end   = tmp;

      if ((start.part == 23) && (end.part == 1))
      {
        start.part = 1;
        end.part = 23;
      }
    }
  }

The comment describes what the code is doing (and shows an example; I'll admit, the comment could be a bit better). But notice how the commit describes why I made the change—it's a comment on the comment as it were.

Friday, January 30, 2015

Your surreal moment of the day

An abominable sight of monks (no, really!) chanting “Losing My Religion” (no, really!).

That is all.

Thursday, January 29, 2015

A Software Archeological Approach to the First Video Game

At the Higham Institute sessions some months back, he and his friends had discussed the criteria for the ultimate display hack. Since they had been fans of trashy science fiction, particularly the space opera novels of E. E. “Doc” Smith, they somehow decided that the PDP-1 would be a perfect machine to make a combination grade-B movie and $120,000 [about $950,000 today —Editor] toy. A game in which two people could face each other in an outer-space showdown. …

Peter Samson, for instance, loved the idea of Spacewar, but could not abide the randomly generated dots that passed themselves off as the sky. Real space had stars in specific places. “We'll have the real thing,” Samson vowed. He obtained a thick atlas of the universe, and set about entering data into a routine he wrote that would generate the actual constellations visible to someone standing on the equator on a clear night. All stars down to the fifth magnitude were represented; Samson duplicated their relative brightness by controlling how often the computer lit the dot on the screen which represented the star. He also rigged the program so that, as the game progressed, the sky would majestically scroll at any one time the screen exposed 45 percent of the sky. Besides adding verisimilitude, this “Expensive Planetarium” program also gave rocket fighters a mappable background from which to gauge position. The game could truly be called, as Samson said, Shootout-at-El-Cassiopeia.

Another programmer named Dan Edwards was dissatisfied with the unanchored movement of the two dueling ships. It made the game merely a test of motor skills. He figured that adding a gravity factor would give the game a strategic component. So he programmed a central star a sun in the middle of the screen; you could use the sun's gravitational pull to give you speed as you circled it, but if you weren't careful and got too close, you'd be drawn into the sun. Which was certain death.

Before all the strategic implications of this variation could be employed, Shag Garetz, one of the Higham Institute trio, contributed a wild-card type of feature. He had read in Doc Smith's novels how space hot-rodders could suck themselves out of one galaxy and into another by virtue of a “hyper-spatial tube,” which would throw you into “that highly enigmatic Nth space.” So he added a “hyperspace” capability to the game, allowing a player to avoid a dire situation by pushing a panic button that would zip him to this hyperspace. You were allowed to go into hyperspace three times in the course of a game; the drawback was that you never knew where you might come out. Sometimes you'd reappear right next to the sun, just in time to see your ship hopelessly pulled to an untimely demise on the sun's surface. In tribute to Marvin Minsky's original hack, Garetz programmed the hyperspace feature so that a ship entering hyperspace would leave a “warp-induced photonic stress emission signature” a leftover smear of light in a shape that often formed in the aftermath of a Minskytron display.

The variations were endless. By switching a few parameters you could turn the game into “hydraulic Spacewar,” in which torpedoes flow out in ejaculatory streams instead of one by one. Or, as the night grew later and people became locked into interstellar mode, someone might shout, “Let's turn on the Winds of Space!” and someone would hack up a warping factor which would force players to make adjustments every time they moved. Though any improvement a hacker wished to make would be welcome, it was extremely bad form to make some weird change in the game unannounced. The effective social pressures which enforced the Hacker Ethic which urged hands-on for improvement, not damage prevented any instance of that kind of mischief. Anyway, the hackers were already engaged in a mind-boggling tweak of the system they were using an expensive computer to play the world's most glorified game!

Hackers: Heroes of the Computer Revolution

Whenever I read Hackers, I was always wanted to play the version of Spacewar described and see the code. Sure, I had played the arcade version multiple times, and I even had a version of Spacewar for the IBM PC that I ran through a disassembler, printed the results and spent a summer going over the code (okay, this was back when I had the time to do such things, in high school) to see how it worked, but neither version sounded quite like the description in Hackers.

Now, thirty years later, computers are now fast enough that an emulator of the original Spacewar can be written in a scripting language and run on a web browser! Even better (well, for various values of “better”) is the extensive writeup about how Spacewar works, along with the actual source code (along with explanations of how one programs the PDP-1, a 5MHz 18-bit 1's complement machine with 4,096 18-bit words of memory.

My, how far we've come in 50 years.

Wednesday, January 28, 2015

Loving County, Texas

… his phone rang with an old-fashioned warning: “You don't know it, but you're in trouble.” A group was planning a takeover of the county, said the caller, a woman in Arizona who promised to send him some information by e-mail. The material described the plans of a Libertarian faction in its own words “to win most of the elected offices in the county administration” and “restore to freedom” Loving County.

…

The goal, said an e-mail message attributed to a group member, was to move in enough Libertarians “to control the local government and remove oppressive regulations (such as planning and zoning, and building code requirements) and stop enforcement of laws prohibiting victimless acts among consenting adults such as dueling, gambling, incest, price-gouging, cannibalism and drug handling.”

…

Now pictures of the three decorate a poster on the sheriff's door at the Loving County Courthouse under the timeworn Wild West legend: “Wanted by the Texas Rangers.”

1 Cafe, 1 Gas Station and 2 Roads: America's Emptiest County

Oh real life! You are so much better than satire these days.

The new video card, round two.

Last week, I initiated a return of the video card with Amazon. I stated my reason for returning it:

I received an ATI Technologies Inc RV370 [Radeon X300SE], which works, but is not what I ordered.

and I was informed that I should hear back from the third party company I ordered the video card from in less than 48 hours.

Nearly a week later, and I had yet to hear back.

I logged into Amazon to lodge another complaint when I stumbled across the message the third-party company sent to me (the following day, on the 21^st), along with the error that prevented the email from being delivered:

Final-Recipient: rfc822; Sean Conner <sean@conman.org>
Action: failed
Diagnostic-Code: smtp; 554 4.4.7 Message expired: unable to deliver in 840 minutes.<450 <sean@conman.org>: Recipient address rejected: Service temporarily unavailable>
Status: 4.4.7

XXXXXX! Amazon ran afoul of my greylisting daemon (Amazon is acting as a proxy between me and the third-party company—neither one of us has the other's true email address).

Checking the logs confirmed what I suspected happened: every attempt by Amazon to deliver the email came from a different IP address, which caused the greylist daemon to treat each attempt as a separate email and thus, block each attempt.

Sigh.

Once that was cleared up, I got the story as to what happened. The third-party company had run out of the video card I requested, and since the card they sent contained the same connectors and amount of memory, they felt it would be acceptable. Had I the right drivers, it might have been acceptable. But I didn't, so it won't.

The third-party company apologized for sending the wrong card. They also said they just received a new shipment of the video card I did order and they're sending one to me. All I need to do now is return the original card they sent back once I get the right card.

So … round three!

We shall see how this goes …

Those Compiler Warning Blues

It's always instructive to crank the warning level up on compilers. It also helps to use different compilers since they tend to warn about different things. With GCC, I use -Wall (which sadly, isn't all possible warnings) but today I learned that clang (the default compiler on Mac OS-X these days) has a -Weverything option, so hey, why not try it?

Wow!

It's not kidding—it warns about everything! Missing prototypes, gratuitous use of packed structures, added padding to structures, signed conversions (not only unsigned to signed, which I can see possibly losing information, but signed to unsigned, which doesn't), loss of interger precision, relying on auto-conversion of function calls (in my case, assigning the result of a function that returns a double to an unsigned long long variable), alignment changes in unions, even “default label in switch which covers all enumeration values.”

It's a lot of output to pour through. And this is for code that passes cleanly through GCC.

But in the ton of “legal, even if a bit questionable C” it still managed to find a real bug in my code:

In file included from common/XXXXlib.c:11:
third_party/uuid/src/uuid.h:34:17: warning: 'SHORT_MAX' is not defined, evaluates to 0 [-Wundef]
#if RAND_MAX == SHORT_MAX
                ^

It's a typo—it should be SHRT_MAX (apparently, there was a severe shortage of vowels in 70s computing, which is why C got stuck with a bunch of vowel-impaired identifiers—sheesh!) but at the same time, it's perfectly legal C, which is why I never noticed this until now.

Tuesday, January 27, 2015

A fine line indeed

In C (and Lua, PHP, Python and just about any other language you'll find on Unix), you use the function strftime() to format a timestamp based on a format string. I always have to look up the format when I want to use it, but hey, it's not like I do it all the time (otherwise, I wouldn't have to look this up).

Anyway, it seems that Go is … different (of course! Rob Pike & Co. know better and feel that replacing the entire development chain is the way to go, what with mandating a coding style in the language design and a static-only linking technology straight from the 70s and its own runtime and standard library … but I digress), and I'm still trying to decide if the approach is stupid or clever—to specify the format with an example! (link to this via Hacker News).

const (
        ANSIC       = "Mon Jan _2 15:04:05 2006"
        UnixDate    = "Mon Jan _2 15:04:05 MST 2006"
        RubyDate    = "Mon Jan 02 15:04:05 -0700 2006"
        RFC822      = "02 Jan 06 15:04 MST"
        RFC822Z     = "02 Jan 06 15:04 -0700" // RFC822 with numeric zone
        RFC850      = "Monday, 02-Jan-06 15:04:05 MST"
        RFC1123     = "Mon, 02 Jan 2006 15:04:05 MST"
        RFC1123Z    = "Mon, 02 Jan 2006 15:04:05 -0700" // RFC1123 with numeric zone
        RFC3339     = "2006-01-02T15:04:05Z07:00"
        RFC3339Nano = "2006-01-02T15:04:05.999999999Z07:00"
        Kitchen     = "3:04PM"
        // Handy time stamps.
        Stamp      = "Jan _2 15:04:05"
        StampMilli = "Jan _2 15:04:05.000"
        StampMicro = "Jan _2 15:04:05.000000"
        StampNano  = "Jan _2 15:04:05.000000000"
)

Yes, you specify how you want the date formated by writing out January 2^nd, 2006, at 3:05 PM in Mountain Standard Time (of course!) however you want it. Never mind that the 1-2-3 sequence is the American “month-then-day” format (Europe? Isn't that near New England somewhere? Across some pond or something).

Now, it's not the first language to specify output using an example. Some versions of Microsoft Basic had that feature to specify numeric output, but I've never seen anything quite like this.

And the justification for it?

I think the litmus test is that if a function's usage is so hard to remember that someone is motivated enough to create a domain and web site whose only purpose is to make it easier to remember where to find the documentation, then that function is broken. (http://strftime.org/)

Time.Format doesn't need to be the kitchen sink. If you need more control, there is always fmt.Sprintf. Unlike C's struct tm, Go's time.Time does not require the addition of magic constants to turn struct fields into printable values.

Time formatting - Google Groups

I'm still unsure how I feel about this.

Monday, January 26, 2015

On napping

Ah, after work naps. How do I love thee? Let me count the ways …

Zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz

Sunday, January 25, 2015

The Meow of HTTP status codes

If you were ever curious about the various status codes of HTTP, or if you like cats (or both!) then you might want to check out HTTP Status Cats (link via BoingBoing).