Keyvan Nayyeri

It’s almost two months that I’ve been publishing regular posts about iPhone/iPod Touch development for an educational system that we’re building for our graduate Software Engineering course. After an overview, I talked about the vision of our project then discussed the deployment process of an iPhone application and introduced the Xcode IDE and Interface Builder.

As I stated before, we decided to choose CrunchTime as the name of the Reverse Polish Notation calculator that we’re building for our project. One of the early requirements for this project was to provide functional specifications of what we want to build.

Personally, I’m not a big fan of some formalities in Software Development especially functional specifications because in my experience these are the most fragile part of a software project that will change before anything else.

Interestingly, functional specification is a gray area of Software Engineering where you can’t find a concrete definition for the expectations from such a specification. Software teams have different approaches to functional specifications. Some of them use a formal method, some use a semi-formal method, and others use an informal method for defining the functional specifications.

Therefore, at the beginning we had some debates to find the best way to implement the functional specifications with my teammates. I proposed a method that combines all the formal, semi-formal, and informal approaches together in which we could start with some user stories as an informal basis, then write a short description of the user stories as a semi-formal structure, and finally provide a concrete solution as the formal part of the specification.

But one of my teammates did some research and introduced a better idea based on some blog posts by Joel Spolsky that describe a painless functional specification (Part 1, Part 2, Part 3, and Part 4). We all agreed to follow his approach that I describe shortly here.

We started with a short overview of the project and its purpose then collected all the user stories that we had prepared before, and prioritized them in different levels based on their importance and the expected implementation time. Basically, we had 12 user stories that we grouped in 3 levels. We described a short description for each user story as well.

In the next section we tried to discuss the main features of the system and describe the purpose and structure of them. This includes the keypad, temporary storage area, and stack as the mechanics of our RPN calculator.

Having a good definition of our basic components and what the users expect to get, we defined three phases for the project to implement it:

• The first phase includes the core features necessary for the basic operations of the system.
• The second phase includes some additional features that are common to such calculators.
• The third phase includes some enhanced features that are worth having but our timing limitations may not allow us to implement them for this educational project.

We also provided a detailed description of our expectations and approximate timeline of each phase.

In the end we also provided a short conclusion of the whole specification. This specification was neither so long nor so short, and we could manage to provide a satisfactory document that addresses the end user needs, our limitations, some plans to accomplish the goals, and a good prioritization of the requirements to implement the important features earlier.

We wrote these functional specifications almost one month ago and now we have almost completed the implementation of the first phase of our project. It looks like that we designed a good specifications document that was realistic and has reflected everything very well.