Chip's Quips
A tiny spark of wit for a highly flammable world

Chipping the web: May 14th

May 14th, 2009 10:00:33 am pst by Sterling Camden

Chipping the web

Posted in Share the Love | 2 Comments » RSS 2.0 | Sphere it!

Chipping the web: October 16th

October 17th, 2008 7:00:17 am pst by Sterling Camden

Chipping the web

Posted in Share the Love | 7 Comments » RSS 2.0 | Sphere it!

links for 2008-06-06

June 6th, 2008 1:34:20 am pst by Sterling Camden

Posted in Share the Love | 2 Comments » RSS 2.0 | Sphere it!

links for 2008-05-22

May 22nd, 2008 1:34:36 am pst by Sterling Camden

Posted in Share the Love | 5 Comments » RSS 2.0 | Sphere it!

links for 2008-03-14

March 14th, 2008 2:26:18 am pst by Sterling Camden

Posted in Share the Love | No Comments » RSS 2.0 | Sphere it!

Requirements specification for writing a requirements specification (excerpt)

October 29th, 2007 2:30:13 pm pst by Sterling Camden

Use cases

Primary actor

Author

Stakeholders

Developer
Tester
Documentation specialist
End user
Technical support

Preconditions

The Author is expected to be omniscient and inerrant with regard to the problem domain.

Primary flow

  1. Author estimates how long it will take to write the specification, a number usually extracted from the anterior portion of Author’s digestive tract.
  2. Author analyzes and documents the feature in English, a different language than that used in the subsequent implementation.
  3. All stakeholders review and eventually sign off on the specification, without paying attention to what it actually says. Much time is spent correcting the use of “shall” and “may”.
  4. Developer ignores the specification, and implements the feature “the way it should work.”
  5. Tester painstakingly constructs tests for every requirement in the specification, including the eventuality of a Category 5 hurricane.
  6. Most of those tests fail, to the secret glee of Developer — who suggests that the specification be modified.
  7. Author duly modifies the specification based on a misunderstanding of the implementation.
  8. Documentation specialist documents the feature based on a misinterpretation of the original version of the specification.
  9. Author and Developer review the documentation, ignoring those errors. They each suggest numerous, conflicting modifications to correctly paint the important role played by their chosen framework.
  10. End user discovers a problem with the feature and calls Technical support.
  11. Technical support informs End user that the supposed “bug” is actually part of the design, and is in fact a highly valued feature provided by the chosen framework. Technical support takes every pain to politely insure that End user is fully aware of his/her own ignorance in this matter.

Alternate flows

4. Developer worships the specification, and slavishly implements the feature according to the letter thereof — especially its mistakes.
8. Documentation specialist becomes aware of modified specification, and adjusts the documentation to misinterpret the newer version.
10. End user discovers a problem, but doesn’t bother to call Technical support because he/she has already had his/her self-esteem sufficiently lowered by his/her boss that day.

Exceptions

Author and Developer understand each other completely, all tests pass, Documentation specialist’s interpretation nails the specification and behavior, and the End user is happy with the feature. This is an unlikely scenario, but should be documented here in order to insure that it is prevented.

Specific Requirements

1. Author

1.1 Author shall gather all use cases and exceptions for the feature prior to writing any code.

1.1.1 Omission of any use case or feature shall throw an AuthorOmniscienceFailureException.

1.2 Author shall provide an accurate estimate of the time required to write the specification.

1.2.1 Failure to meet or beat this estimate shall trigger an analysis of Author’s failings. Depending on the determined source of failure, one of the following exceptions shall be thrown: ExcessiveWorldofWarcraftException, InterviewingFrequencyException, BlogOverflowException, or the more general LazyAssAuthorException.

(etc.)

Posted in Geek Meditations, Wildly popular | 6 Comments » RSS 2.0 | Sphere it!

Mammoth projects

December 10th, 2006 5:58:08 pm pst by Sterling Camden

Recently I finished a large project. No, “large” isn’t the word. Mammoth.

As far as the number of lines of new code written goes, it wasn’t that big. I only added three new source files. But the impact of the new features required subtly re-engineering hundreds of small sections of code in 45 source files in four languages. Some of this code is over 15 years old, and has been evolving fairly steadily for that whole interval. The changes were so pervasive that there was no way we could release it in phases. I don’t think that anybody would have been able to pull it off without the kind of intimate knowledge of the code in question that I possess. Still I worry that any one of those hundreds of modifications might turn into a bug factory.

Why would my client and I agree to plunge into that kind of project? Why consume a ton of hours to risk the stability of a thriving product?

Customers wanted the central feature so badly that they were already hacking it in, with limited success. The resulting unanticipated software interactions increased the number of support calls. One of the chief hackers was none other than yours truly, which brings me to my next point.

I had already created a pretty good prototype. It was about an 80% solution. More importantly, it identified areas that would need to be addressed in a full implementation, because a lot of users adopted it. The prototype only took me a day or so to whip up, but it revealed to-do’s that would consume months of development. Thus,

We knew the scope of the project going in. OK, even so we underestimated the time requirements. But that underestimation would have been an order of magnitude off without doing the research and laying out the requirements up front.

Users were involved from the start. We asked them to help us develop and review the requirements. We looked at their use of my prototype and other existing hacks to make sure we could answer the problems they were trying to solve.

We have a strong set of tests for existing features. We felt confident that we could avoid introducing bugs into users’ applications when we released the product, even if the schedule might have to expand to fix them first. Naturally, we also developed new tests for the new features, based on the requirements. Most of those tests were developed just ahead of the implementation, so my new code was being tested before the ink was dry. That allowed me to fix problems while the design was still fresh in my head.

Documentation was authored simultaneously with development. That raised a number of questions along the way that helped us identify inconsistencies and potential problems.

Long beta test, with quick updates to the beta testers as needed. No matter how many and varied your QA tests may be, your users will find their own unique ways of using the product. And Murphy says that if you break something, it will be the one thing they use every day. So you want to find that out long before release date.

That’s where it sits now, in beta. So far, I’m not being flooded with bug reports, and my client seems happy with the result. A mammoth project isn’t necessarily doomed to extinction.

Knock on wool.

Posted in Geek Meditations, Wildly popular | No Comments » RSS 2.0 | Sphere it!

Rats on Rails

February 10th, 2006 10:47:35 pm pst by Sterling Camden

My career in software development started quite by accident. I started working with computers because I couldn’t type. I still can’t. I never took typing, but over the years my hunting and pecking has achieved a mind-numbing speed. But back to the story, when I started courses at the university, part of my funding was to come from the work-study program. Financial Aid sent me to the Dean of Student Affairs’ office to be a typist. After witnessing the sheer futility of any attempts that I made to coax words out of a typewriter and onto the paper, the Dean sent me back to Financial Aid. So, they picked another job out of their figurative hat and sent me to Data Processing, as it was called then.

I climbed the two flights of stairs to the Data Processing department, a cold set of rooms with no windows, raised floors, and a noisy air conditioning unit. I sat down for an interview with the D.P. manager, David Lee (wonder whatever happened to him?), who asked me if I was a Computer Science major. I wasn’t — in fact I majored in Biblical Literature. It was 1978, and I had never seen a computer. I had no idea which end to put in my mouth. I replied, “No, but I learn fast.” I guess he was short on prospects, because he replied, “Well, all you really have to do is tear the printouts off the printer and carry them down to the student lab and sort them by the student’s last initial.” I said, “Well, I know my alphabet.” So I got the job. He forgot to mention things like paper jams in those old line printers, or angry students who had been waiting for their compile jobs to print out for four days only to find that they forgot a period in a COBOL program.

Anyway, I became very intrigued with computers while working there, especially after I was introduced to computer games. The Adventure game was the first I played, and I was amazed how you could type in commands and the computer would respond with changes to a simulated world (all text-based back then!). Another game I really liked was called Rat Race. It was written in AOS BASIC and ran on a Data General Eclipse C-330. It featured ten “rats” (represented by the digits 0-9, remember this was on the old 24 x 80 text-only terminals of the day, like the 6052) who were lined up in lanes that ran across the screen. The rats had names and races/wins/places/shows records that were stored in a crude database (fixed-length sequential file). They were randomly picked for each race, and random numbers were used to decide which rat to move forward on each cycle of the race. The random pick was biased according to their past records, so a rat who performed better in previous races would be favored. Their odds were computed according to the same factor and were displayed on the screen. The race just ran on and on, and you could observe the records and odds of each rat change the longer it ran.

I was mesmerized. I taught myself AOS BASIC from the book, Basic BASIC, which I don’t think is in print anymore. I remember the hardest thing to get my head around at the beginning was the statement X = X + 1. That doesn’t solve in algebra. Finally I realized that every programming statement is a command (or at least was in those old languages) rather than a statement of fact. With BASIC well in hand, I started writing some simple games like blackjack and craps. Finally, I was ready to dig into the workings of the Rat Race (being written in BASIC meant that we had the source code — muwahaha!). I made some enhancements to the game: I made the game randomly choose to move one of the rats backwards, again biased on their past performance. I also added betting, so up to five observers could bet on a rat, and the game would pay them full odds for the winner, half that for place, and a third of that for show.

I continued to teach myself programming languages, including COBOL, DG/L (a form of Algol), Eclipse Assembler, Fortran and more. By luck or providence I decided to stay there for the summer one year and work full-time in D.P., so I was in the right place at the right time when all of the programmers either quit or were fired. That made me the one person who knew more than anybody about the system, and I knew next to nothing. So I dug in and devoured as much of the code as I could day by day. Along came languages like PL/1 and MUMPS. When I finally graduated with my Biblical Literature degree, they hired me on as a full-time programmer.

Less than a year later I got a call from a head-hunter who asked me if I’d like to change jobs. I went on two interviews and accepted a position on the second one, Digital Systems of Florida (the first one, Datapoint, later made an offer as well — back then you only needed to know how to program to get a job). Digital Systems made me the only programmer on their Depreciation package. This was right after the ACRS rules went into effect, and all I knew about Depreciation was that things rust. They also employed a language I had never seen before: DIBOL. Nevertheless, I dug in and learned it, and I got the project done ahead of schedule.

That, and the fact that I knew several other programming languages, caught the attention of the Research & Development department, who were actively pursuing options for their next generation of products. They moved me over and introduced me to UNIX and C. How wonderful! I couldn’t believe how powerful these tools were. To thoroughly teach myself C, I decided to rewrite the Rat Race in C. I didn’t have the BASIC code anymore, but I remembered the algorithms pretty well, and reproduced it faithfully. The only problem was, it was too fast. The rats would all run across the screen before you could even see them, and that version of C did not have a sleep that accepted fractional seconds. I didn’t want to wait a whole second between movements, but I found that if I made the program display 80 blanks across the bottom row of the display between each rat movement, the pace was pretty good.

Later, the R&D department began doing a lot of process-control work to automate software distribution. This was on DEC PDP-11′s running RSX-11M, and the language of choice was Fortran-77. I knew Fortran 4 & 5 tolerably well, but to get down and dirty with Fortran-77, I decided the Rat Race was the way to go. I converted the C version over to Fortran-77 in no time, and in the process learned all about file and terminal I/O in Fortran-77.

Finally, we decided that the next generation of accounting products would stick to the same language they had been using for some time: DIBOL. This language had started out on PDP-8′s and moved to the PDP-11′s, and a company called DISC (now Synergex) had a new version (called DBL) that was portable to MS-DOS and many flavors of UNIX, and also added some great language features that were missing from DEC’s implementation. I had struggled under the limitations of the DIBOL-11 compiler ever since I arrived at Digital Systems, so I couldn’t wait to test out all of the new language features. You guessed it, I rewrote the Rat Race in DBL version 4.

DBL v4 added fixed-point decimal numbers to DIBOL (prior to that, all numbers had to be stored as whole numbers and you had to handle any implied precision yourself), and I made use of this feature in the odds and random movement calculations of the Rat Race. Being a new feature of the language, I discovered a bug in it. So, I sent my Rat Race to DISC so they could figure it out. They loved it. Not only did it help them solve the bug, they realized that it made a great performance benchmark for disk and screen I/O, as well as arithmetic processing. So they asked if they could keep it in their test suite. Of course, I agreed.

Well, years went by. I was promoted into management at Digital Systems, which later changed its name to CPAS (now CPASoftware, or Sage Software). We were again exploring options for a next generation of applications, and we were introduced by DISC to their newly developed Toolkit product. After examining it thoroughly, I decided we should go with it. Then I found out that somebody at DISC had updated the Rat Race to use the Toolkit.

Anyway, as we began implementing the early versions of the Toolkit, we naturally ran into many issues, and I worked closely with DISC on resolving those. We were allowed access to the source code for the Toolkit, and many times I would just write a solution and hand it to them. This resulted in them becoming my first client when I became an independent software consultant. They are still one of my best customers, and I have helped them add many features to the Toolkit, including porting it to Windows!

In the years that have passed since then, the Rat Race has surfaced from time to time. In 1992, after Visual Basic 2.0 was released, I decided to write a graphical version to learn that language. I created crudely animated rats using four images that randomly changed. Unfortunately, I didn’t understand that VB’s coordinate system used twips, so it only displayed properly if you ran it on the same screen resolution as the computer I developed it on (800 x 600). I never found the time to fix that.

In 1998, after learning Java, I rewrote it as a Java applet, using the same crude mouse animations I created for the VB version. Unfortunately, I never got around to figuring out how to tie it into a back-end database, so it always ran a race between ten rats named “Anonymous Rat”.

Finally, just this month, I decided to rewrite it again. This time, in Ruby on Rails. In a previous post, I mentioned that I would be evaluating this framework, and I can say that it is definitely a Good Witch. The animation is still just as crude, but this time I used Rails to provide the database access. Rather than having an applet or ActiveX control that has to be loaded into the browser, I used the AJAX capabilities of Rails to achieve the animation. Unfortunately, this means that we have about a second’s delay between each update, but it’s still pretty entertaining. I haven’t added betting to it yet. I’ll have to think on that one with a web model. I must say that implementing this in Ruby on Rails was considerably simpler than any implementation to date, including the older character-based versions.

This exercise not only taught me a lot about Ruby, Rails, and AJAX, but also revealed some interesting differences between browsers. You can read all about it and download the whole thing here.

Posted in Coding...OK?, Wildly popular | 8 Comments » RSS 2.0 | Sphere it!

Better Tag Cloud