Can we finish this thing for Agile2017???

As you read this, remember, these articles are for The Book of Erors. And this one’s going to fit right in.

Today is the last working day for Tozier and me, before my trip to Agile2017. If I were a real Product Owner, I’d be pressuring the hell out of the team to get me a version for the conference. Then I could take my iPad to the conference, which I will anyway, and write an article, which probably I won’t.

Many sins are committed in the name of making some date, and as dates go this one makes as much sense as most of them. And this would be a super time to test the thing under live fire. So we’ll take a look, maybe it’s possible.

So, what’s our status? My belief is that the system will run and move the files as needed. So, presumably, if we pointed it at the right folders and FTPs, it would do the right thing. We’d need a timer and file watcher to trigger the job, and not much else. Except that I’d like to be very sure it’s going not going to do anything bad, like destroy my web site while I’m away from home and can’t put it back.

We’ll talk about it. We’re pretty optimistic that we’re close enough to just¹ finish it up and ship it.

Tozier arrives around 9:30. We discuss backing up my whole web site and writing to the copy. I think with 5,000 files and finite time, not gonna do it. We dig into the code and tests and decide to write a test that runs in my real site folder, but does the FTP transfer to a new testing folder, which we can then inspect:

  def set_up_for_really_jekylling
    # root here is /Users/ron/programming/test-ftp
    new_files_folder = '/Users/ron/Dropbox/_articles_from_ipad'
    jekyll_folder = '/Users/ron/programming/rj.com'
    ftp_host = 'localhost'    # ftp.ronjeffries.com ?
    ftp_target_folder = '/Users/ron/programming/test-ftp/_scary_target'    # httpdocs
    password_prefix = 'TEST_' # PROD_
    return JekyllRunner.new(new_files_folder, jekyll_folder, 
      ftp_host, ftp_target_folder, password_prefix)
  end

  def test_in_live
    jr = set_up_for_really_jekylling
    jr.run
  end

The test fails complaining that it cannot find the source folder, '/Users/ron/programming/rj.com'. We weren’t sure whether we were looking too deeply, though we were sure that path will start at the appropriate root. We printed out some information, we wrote some special tests. We tried escaping the dot in rj.com. We burned through about an hour trying to figure out what was wrong.

The name of my Jekyll source folder is rj-com, not rj.com. It’s visible at the top of my Sublime editor, and we looked at it several times in Finder.

Once that massive error was corrected, we quickly made the new test run, primarily by making sure that all the pre-required folders were present. (Recall that we erase and set up the target folder for the other test: we had not done that for this one “because we’ll only run this test once”. Haha very funny.)

Anyway, this test finally runs correctly, leaving us with only building the production main program, the cron job, and the file watcher. Unfortunately, our two-hour programming window had elapsed. Ron will not have the ability to write article on his iPad at Agile2017 and publish them. So please, if you see him, don’t ask him to do it, it will make him sad. Unless you want to make him sad.

Summing Up

This article is part of The Book of Erors, and it’s about the difference between plan and actual, about the Mangle of Practice, about what really goes wrong behind the scenes in all those articles you read about how easy it really is to program, and about why you shouldn’t believe even your own estimates about when you’ll be done.

What happened? A stupid, simple mistake. I typed “rj.com” thinking about “ronjeffries.com”, and the three (3!) other people sitting with me also didn’t spot it, and we worked on it for over an hour before realizing I meant “rj-com”. I say “realizing”. I think that what happened was that Tozier’s wife, Barbara, who had joined us for the morning, finally saw the key thing or asked the key question. And she’s not even part of the project. (Smarter than the other three of us, though.)

That search for the missing dash, followed by a few quick fixes, used up all the time we had available, and the whole thing was an incredible gumption trap.² We had no energy left to do the rest, and we had lost our youthful confidence, so we didn’t even really believe we could finish.

Now if this were a real job and our boss were a real jerk, we might have pressed on, pulling an all-nighter or all weekend push to get the product out. We’d have been working tired and demoralized. We’d have been short on time and patience, and while we might get it working, there’s not much chance we’d get it working clean.

It’s fascinating to me how this little part-time project seems to duplicate so many of the things that go wrong on larger projects. We get confused over the requirements. We can’t quite figure out how to test something. We write part-way tests that need to be removed or updated later. We make ad-hoc decisions on data structures that need revision, and we get tied into system APIs that aren’t quite right for our needs. We put the same or similar code or information in multiple places and then forget to change them all when we should. We make dumb mistakes and waste hours looking for them.

These are the same things that plague us when we’re working on real, larger projects, with real, larger teams. There may be some common issues that we don’t encounter, but perhaps not many. In a larger team, we might not know some parts of the code well. We simulate this, accidentally, by only working a couple of hours two days a week.

I expect that the fixes and compensations for these problems will be the same as well, a relentless attention to having the right tests, and to expressing meaning in both our code and in our tests. Clean code, well tested, seems to me to be our best bet.

Some people will tell you that you can trade off code quality for speed, somehow going faster by writing inferior code. If there’s any lesson to learn from these articles, consider this one:

Cruft Kills

On this project, we get in trouble, almost every time, just a few hours after writing inferior code. It may take longer before you stumble on yesterday’s mistakes, as you move around in a larger code base. But the mistakes are there, and you will stumble.

Learn from these examples. Cruft kills.