Blogging Ottinger (tim)

This is why documentation and learning by yourself is never as good as having actual programmers pair with you. I’m working form the pylons reference documentation, which has a number of tutorials in it. They would be nice, but they’re just so wrong.

I suspect that most of section 3.2 is wrong and/or broken

Note the explanatory text here. It describes the three import lines. Of which we have the second only. And it’s not used. We don’t have an import in this code for ’sa’, but we use sa.Column and not Column. So the second import is essentially useless. The only exception is where it uses Table. I replaced it with sa.Table and it worked fine. The import was a waste.

But where does sa come from? Well, if you have the right version of pylons then it imports sqlalchemy as sa at the top of the file. If you are not using the right version, it does not and your code won’t work at all until you import sqlalchemy as sa.

Next paragraph begins by describing code that does not exist in the sample. The last half of the paragraph is right.

Does this mean the pylons people are dumb? No. It means that the documentation hasn’t kept up even with itself. Over time it becomes self-inconsistent because it can. It takes vigilance to keep a documented truth in one release from turning into a lie in the next. That’s why you need noobs like me to come along and find out that the docs are all messed up.

Once a document is wrong you doubt the rest of it. It asks me to add code that is similar to code added by paster, but slightly different. Do I do that? Or is the documentation wrong again? If it doesn’t work, what do I do as a novice? If it does work, then does that mean the the code paster added is wrong and the tutorial is right? Do I need to undo paster work each time? Hmmmm.

Documents are an ongoing expense. They have to be constantly validated and verified. This is why agile shops tend to use pairing and prefer documents that self-verify (tests). Pylons is nice stuff, but you need to learn it from somewhere.

Pylons guys: please fix these. This is from the quickwiki tutorial. I love python and am eager to go further with pylons, but the tutorial is hard on the newb.

Come to Agile In A Flash where my collaborator Jeff Langr and I will provide you the shortest, fastest, most ready-to-hand agile references to be found anywhere.

A common situation is explained at AgileOtter (my professional blog).

Just because Stack Overflow offers a RSS Feed don’t think that you should necessarily subscribe to it. Not unless you happen to have fifteen or twenty extra hours to spend on feed triage each day. I subscribed two days ago, and I have already done the “mark all read” at least twice on this feed.

Talk about drinking from a firehose.

I’m glad to have pyfit, mostly because I’m glad to have something that works like fitnesse works. I’m not a huge fitnesse fan (it has some serious issues) but I’m a user.

However, the pyfit internals are pretty confusing to me. Today’s bit is really odd. There is a function in Variations. py called returnVariation() that takes a parameter called env. That argument is never used in the function and never passed to any other function it calls. Note that there is even a __pychecker__ trick there to turn off the syntax checker’s warning about unused parameters.

Generally the function is called and the return value is ignored. Clearly we’re dependent on side-effects here.

def returnVariation(env=None):
    __pychecker__ = \"no-argsused\"
    if FitGlobal.Environment == \"FitNesse\":
        result =  FitNesseVariation()
    elif FitGlobal.Options.standardMode:
        result =  StandardVariation()
    elif FitGlobal.Options.useCSS:
        result = FitVariation()
    else:
        result = StandardVariation()
    FitGlobal.annotationStyleVariation = result
    return result

If you drop the argument, then tests stop passing.

def returnVariation():

Even though it’s never used and never passed. Even if you drop the parameter and set env to None:

def returnVariation():
    env=None
    __pychecker__ = \"no-argsused\"
    if FitGlobal.Environment == \"FitNesse\":
        result =  FitNesseVariation()
    elif FitGlobal.Options.standardMode:
        result =  StandardVariation()
    elif FitGlobal.Options.useCSS:
        result = FitVariation()
    else:
        result = StandardVariation()
    FitGlobal.annotationStyleVariation = result
    return result

There is one place where the function is called, passing a string value as env, otherwise it is always None, and it is still never passed to any method or installed in a global/local/module variable. But it somehow causes tests to fail if you remove it.

Wow.. talk about programming with a ball and chain on!

Arrrgh!

You should NEVER use the lower-case L as a variable name. Ever. Especially if you’re going to have it in proximity to a 1 (which is a one, a fact that I have to call out because it looks like the l, which is an L). Ever. Never ever ever. Even in Python, which is one of the most readable languages in the world when it’s done correctly.

   2  def perm(l):
   3      sz = len(l)
   4      if sz < = 1:
   5          return [l]
   6      return [p[:i]+[l[0]]+p[i:] for i in xrange(sz) for p in perm(l[1:])]

The algorithm/snippet is okay, other than the choice of variable names, with is quite dreadful all the way through.

URL withheld to protect the butthead.

Updated 8 Sept 2008, from friends’ comments

A friend asked me how to do this, and I didn’t really understand the question at first. Finally I figured out the answer and mailed it back. It’s a reasonable question, so maybe it should get a place in my vim wall of fame.

1. You mark and yank your text, and it goes into the register named ” (doulbequote).
2. You go to the new place and mark the stuff you want to replace (as usual).
3. Now either:
   1. You press ‘p’ to “put” the default register over the doomed area
   2. Continue editing as normal.

   or

   1. You press ‘c’ for change. The marked text disappears, and you’re in insert mode.
   2. You type ^R” and it pastes the ” register into the current position.
   3. You press escape to leave insert mode.

Notice that you don’t have to use the default register. You can use any named register, and you have an awful lot of them. If you use register “a” for example, you would use "ay to yank the register. If you were doing a normal put, you would use "ap, or if you were using the change/insert mode you would use ^ra to paste the a register into the marked area.

If you are going to do a lot of search/replace, you’re still possibly better off using “:%s” substitution, but it’s reasonable to use this trick for relatively local replacement of arbitrary regions of code.

After I worked this out, I realized I needed it yesterday. And Monday. Duh. Would have definitely used named register instead of the double-quote default register.

I was really frustrated because I was working via ssh from home to a solaris box. I really don’t know much about solaris, despite having spent time as a programmer on unix boxes (my debian experiences are mostly running apt utilities, which make it pretty easy compared to real sysadmins who know what they’re doing).

So I would get a little ways into the task, pop up a google search, and when I return the session was frozen. Close terminal, open a new one, log in again, stop to think up a new password for the user I’m adding… hung up again. If it weren’t for screen I would have lost my place a dozen times.

Finally I find a bit of help from shapeshed. I figured something was going wrong during idle, but I don’t really know enough about ssh to have figured it out. All I really needed was to set up ServerAliveCount and ServerAliveInterval as directed.

Now my ssh is rock-solid. It is truly a beautiful thing.

Now if only I could get Solaris to cooperate a little. Geez, my VM doesn’t have the man pages indexed for “man -k” usage. It’s not very novice-friendly at all. Looks like I’ll have to fake or borrow Sun expertise.