Mailing List Archive
tlug.jp Mailing List tlug archive tlug Mailing List Archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]Re: [tlug] [OT] Good IT Resume
- Date: Sat, 28 Jul 2007 08:57:28 +0900
- From: "Josh Glover" <jmglov@example.com>
- Subject: Re: [tlug] [OT] Good IT Resume
- References: <8572e260707182339i5ca059c4l1be1f51559c16f54@mail.gmail.com> <d8fcc0800707230647j31bc776dje3e18d57b04352e7@mail.gmail.com> <Pine.NEB.4.64.0707241211330.8162@homeric.cynic.net> <d8fcc0800707240550o691c99f9n4524a2fe71c847e8@mail.gmail.com> <Pine.NEB.4.64.0707251409590.8162@homeric.cynic.net> <20070725072147.GD23731@soto.kasei.com> <d8fcc0800707260050v50c889eawb6a0d426f3dd301b@mail.gmail.com> <Pine.NEB.4.64.0707262024340.26874@homeric.cynic.net> <d8fcc0800707260651j6fab097fi1fdf3a9b2fbb03d8@mail.gmail.com> <Pine.NEB.4.64.0707271740110.10301@homeric.cynic.net>
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/
- Follow-Ups:
- Re: [tlug] [OT] Good IT Resume
- From: Curt Sampson
- References:
- [tlug] [OT] Good IT Resume
- From: Pietro Zuco
- Re: [tlug] [OT] Good IT Resume
- From: Josh Glover
- Re: [tlug] [OT] Good IT Resume
- From: Curt Sampson
- Re: [tlug] [OT] Good IT Resume
- From: Josh Glover
- Re: [tlug] [OT] Good IT Resume
- From: Curt Sampson
- Re: [tlug] [OT] Good IT Resume
- From: Karen Pauley
- Re: [tlug] [OT] Good IT Resume
- From: Josh Glover
- Re: [tlug] [OT] Good IT Resume
- From: Curt Sampson
- Re: [tlug] [OT] Good IT Resume
- From: Josh Glover
- Re: [tlug] [OT] Good IT Resume
- From: Curt Sampson
Home | Main Index | Thread Index
- Prev by Date: Re: [tlug] Post my article on tlug.jp?: Who's view does it represent?
- Next by Date: Re: [tlug] [OT] Good IT Resume
- Previous by thread: Re: [tlug] [OT] Good IT Resume
- Next by thread: Re: [tlug] [OT] Good IT Resume
- Index(es):
Home Page Mailing List Linux and Japan TLUG Members Links