Re: [tlug] [OT] Good IT Resume

["Josh Glover" <jmglov@example.com>]

On 27/07/07, Curt Sampson <cjs@example.com> wrote:

> On Thu, 26 Jul 2007, Josh Glover wrote:
>
> > The customer is happy, and the specification has been specified, but
> > not codified. What happens when you come back to that project in six
> > months and you have no record of the process?
>
> Um...nothing bad? I'm not sure why you would really need a record of the
> process, but I suppose if you're worried you could keep a diary.

Well, why not keep a spec? The spec tries to codify the things that
code just cannot (or at least is not good at), including the rationale
for various design decisions.

Let me give you a (contrived) example of why a spec is useful. Let's
say that you build project X for a customer, and at some early stage
of your specification cycle (and please know that I find nothing wrong
with the way you do specs except for your disdain for a document
resulting from that process) you suggest optimisation Y, which the
customer rejects for reason Z.

Now six or more months later, another engineer goes to work on phase 2
of project X. Not having a spec to look at, and not having you or the
original customer to talk to (you are on vacation in darkest Canada,
stuck in Saskatchewan with only 56K dialup, which you have sworn not
to use on religious grounds, and the original customer has left his
job to found a startup--they are trying to sell marmot insurance to
Buddhist priests), the other engineer also proposes optimisation Y to
the new customer. The new customer accepts readily, and both he and
the new engineer have a laugh at the incompetence of their
predecessors.

Of course, you had a valid reason for not implementing the
optimisation, and you even left comments in the code to that effect.
However, the new engineer refactors away that chunk of your code
because he is implementing optimisation Y, so he never sees your
comment. This causes the customer's company to fail, and they sue you,
and you end up stuck in court for years because, as Keith and Marty
pointed out, judges know about specs and are surprised when you don't
have one.

> If you're looking at code that seems to be doing something odd, just
> "fix" it, run the tests, and you'll quickly be shown the exact test that
> tells you why it's odd.

Maybe.

> Or, if performance was a consideration, run the
> benchmarks before and after and you may see why something was done a
> certain way.

Maybe.

> If you're wondering about the system design, read the code.

Wrong answer! Why should I have to read the code, which will take a
long time and could be quite difficult, just to understand your design
and its motivations? Assuming your code is, say 10,000 lines, I would
expect a technical spec that is at most 1% as long (10 pages). That
would take me an hour or two to read and grok, whereas reading 10,000
lines of code would take ages, and my understanding of the *design*
would be less perfect than had I read the spec, complete with diagrams
and examples.

The bottom line is this: the spec shows how it is supposed to work.
The code shows how it does work. When the spec is kept up to date, any
differences between spec and code mean a bug in the code.

Is your code bug-free? 'Cuz mine ain't.

> Unfortunately, you now have two specifications, and you have to make
> sure that you update the paper one as well as the code one. And the code
> "specification," has executable tests, at least; how do you make sure
> that the paper one is correct after you modify it?

Because the customer reviews it. Which is not to say it will be
perfect, but I would imagine it would have fewer bugs than any code.

Again, what you seem to be missing is the difference between what code
*should* do (which is written in the spec) and what it *does* do
(which is written, perhaps erroneously, in the code).

> I have a full set of executable tests that not only tell me how the code
> is supposed to work, but even test it for me to make sure it really is
> working that way.

OK, test-driven development. Had you used the buzzword, I would have
known what you meant.

Unit tests are great, and the TDD way of writing the tests before the
code is an awesome idea. I use it myself, and let me assure you that
TDD in no way precludes a spec. In fact, it is an excellent compliment
to one.

Specs encode different knowledge than tests.

When I say spec, I really mean two things:

1. Requirements specification
2. Functional specification

The former is the customer's needs, translated into clear language and
diagrams; for a description of the latter, please turn to the Book of
Joel:

http://www.joelonsoftware.com/articles/fog0000000036.html
http://www.joelonsoftware.com/articles/fog0000000035.html
http://www.joelonsoftware.com/articles/fog0000000034.html
http://www.joelonsoftware.com/articles/fog0000000033.html

> > I agree with this in spirit, but if you are really saying that late
> > changes are cheap, I think you are smoking something good, and I want
> > a toke.
>
> I'd love to give you one. Yes, late changes are cheap in my projects.
> I've got projects where I've ripped the heart out of the code and
> completely redesigned it in the week before before a release, and this
> does not cause problems.

Mate, I am also familiar with refactoring, and "Refactoring"[1].

But most of the costs of late changes have nothing to do with code. In
fact, I would argue that for the projects I work on, the engineering
costs are insignificant next to the other costs.

Here are two concrete examples from my work:

1. A project I recently finished added well over $100,000 (US) a
*week* in incremental revenue. Had I needed to make late changes and
the project was delayed a week because of it (and believe me when I
say that there are changes that would take two days of work on my part
and four days of sitting on my hands waiting for some external event
that *must* happen, and I think this is be true at almost all large
companies), you have right there in black and white the financial cost
to the company. Now what if my boss's boss's boss took a look at our
financials and saw that my project had slipped its launch date and
cost us that money? What if, when the next performance review rolls
around, he remembers that and denies my boss's request to grant me 100
units of stock or whatever? Goddamn, that late change was costly, both
to the company and to me personally, and it had nothing to do with
engineering.

2. A project I recently finished required review of the text by the
legal department, a process which takes a week, give or take one
business day. If I had made so much as a *text* change near the end of
the project, it would have delayed launch by about a week. Now imagine
if I had added new functionality! That would have meant engineering
time + retest time (not all tests can be automated, you know) + legal
review time. Yuck.

Again, let me underline that the costs that dominate in software
development are not the engineering costs.

> You may not know how to do this, but I assure you, it can be done. And I
> can teach you how to do it, if you wish.

I will dismiss that as arrogantly tactless, and not a personal slight,
as it seemed in the harsh light of midnight.

> Well, ok, some changes may not be cheap, but they're no more expensive
> than it would have been to make the change closer to the beginning of
> the project. And often you just don't have enough experience to figure
> out what something's supposed to look like until you've done a fair
> amount of implementation work on it.

I take strong exception to this, but we've been over that above.

Cheers,
Josh

[1] http://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672/