Write Specs In The Present Tense

archived comments edit

I have a bad habit of writing specs in the future tense. Since the system I’m spec’ing doesn’t yet exist, it’s so easy for me to fall in the habit of saying things like:

  • This page will look like this:
  • At this point the system will do this.
  • The system will display that control here.

instead of:

  • This page looks like this:
  • At this point the system does this.
  • The system displays that control here.

So what’s the big deal? Well there’s two big deals. Number one is a question of written aesthetics and the other is a more practical consideration. Ok, so they’re not all that BIG a deal. But let me continue.

Aesthetically speaking, using the present tense sounds more active and interesting. Remember all those lessons about active voice and passive voice in high school English? I think it’s made me paranoid.

Secondly, and more importantly, is that after you build the system and someone comes along and refers to you spec as a piece of documentation, it sounds kinda funny to say the system "will look like this" when it already "does look like this". You can argue that the system doesn’t respond till the user interacts with it so that saying "When the user clicks here, the system will navigate there" isn’t so off the mark. See my first point in response to that point. I thank you for your time.

Comments