writing functional specifications manuel rodriguez-martinez, ph.d

Writing Functional Specifications

Manuel Rodriguez-Martinez, Ph.D.

2

Objectives

Discuss issues associated with functional specificationsIdentify best practices to increase your success rate

3

Functional specifications

What are they?Documents describing how the product should behave

Things to includeFeatures of the productUsage scenarios and user profilesHow to use the product screen by screenFlow of actionExpected behavior

4

Why do we need them?

Identify featuresFigure out what technology do we needDetermine expertise needed to build the productUnderstand major components and break down into layersIdentify risk areas and limitationsFocus your development effort on satisfying specsSetup schedule based on all of the above

5

How do get them?

Interview clientWhat do they want to do?

Design patternsWhat solutions can be used?

Prototype featuresHow do major components operate?What features a certain technology provides?

Experience from developersWhat things work and what won’t?

6

Part I: Organizational Issues

Before taking any project and writing any code ask yourself:

Is my organization ready to develop software?Some people believe good developers is all you need

Reality: talent is over rated.Discipline is the key to success

Joel Spolsky – former Microsoft Excel PMInternet blog with many rule of thumbs and ideas

Some are not right IMO

7

Joel Test: 12 Steps to better code

Test 1: Do you use source control?SVN, CVSManage code and integrate with the restKeep backups for free …

Test 2: Can you make a build in one step?Start you application top down

Phase 1 of DB ProjectNo mystery to compile, deploy and run applicationMost IDE create a project that runs! CMSC 435 @ UMD – Software Engineering course

Deliverable –software application with one click installer

8


Test 3: Do you make daily builds?Make sure you new code

Works and does not breaks someone else code ICOM 5016 last day integration syndromeDo it when people are around to fix it Rotate who is responsible for the build

But if someone breaks it that person should fix itTest 4: Do you have a bug database?

Track know bugsPick the ones to fix now and the ones to be left for futureTrack cause, buggy behavior, expected behavior, owner

9


Test 5: Do you fix bugs before writing new code?

Critical bugs must be fixed ASAPEx. Null pointers, number overflows, etc.

You know what are doing and is easier to track what happened

In one week you will forget what the code was doing …

Lots of unfixed bugs == unreliable schedule to finishICOM Software Gurus

Write 5000 lines of undebugged and untested codeExpect to be able to fix them a week before deadlineOften they get bored and quit the project (go to play games)

10


Test 6: Do you have an up-to-date schedule?Schedule is not carved in stoneEach developer must update time to end task

Make sure debugging and testing in includedDo not let manager change time!

Project will fail! Cut luxury features in order to meet deadline

Test 7: Do you have a spec?Functional specification – what the software will do?

Not UML, not layer diagramText and possible GUI sketch

What will happen when people use the codeNo spec == guessing

11


Test 7: Do you have a spec?Spec helps you “debug application”

What is needed and what is not neededRight vs. wrong behavior

Spec helps you control scheduleIdentify required vs. nice to have (luxury) features

Test 8: Do programmers have quiet working conditions?

People like to concentrate and write code (inspiration)Distractions

PhoneConstant questions about schedule or windows crashFar away bath rooms / food / coffee Co-worker interruptions

12


Test 8: Do programmers have quiet working conditions?

One minute interruption == 15 minutes of lost workGive people their own desk with their machine

Test 9: Do you use the best tools money can buy?

Do not torture your developers with Old machines with small monitorsDisk space quotas Outdated OS releaseBad software tools

Microsoft Paint vs. Photoshop for Web imaging

13


Test 10: Do you have testers?UML bug free mythology

Reality: Every software coding effort is full of bugsBad design or bad implementation

Programmer does first test JUnit

Dedicated tester check whole system or subsystem

Unbiased Tries several scenarios and documents anomalies

Testing and coding should be interleavedWrite code, debug, test, write code, debug, test, …

14


Test 11: Do new candidates write code during their interview?

No writing code == uncertain skills == uncertain project member == uncertain project outcomeResume is paper – you can put whatever you wantNeed to make candidates write code

Remove duplicates from a linked listSort data on an array

ICOM 4.0 GPA Students Some of them cannot write codeThey even evade ICOM 5016

15


Test 12: Do you do hallway usability testing?

If your co-workers have a hard time with your GUI the user has no chanceShow people you UI and collect data on

Intuitiveness of UIProblems with locations of buttons, menus, etc.Issues with ease to find desired information

You can go to a more complex usability testing later on

If you cannot convince your coworker you are in troubleRedesigning the UI can be quite expensive

16

Software Products classificationProducts can be classified as

Shrink wrapCustomizedThrowaway

Shrink wrap Targeted to a general audienceEx. MS Office, Photoshop, iTunes

Customized Specific to a given user or industryEx. CESCO David, UPR PATSI, Universal Insurance Claims Management

ThrowawayInternal code used to experiment with a given technologyEx. Phase 1 and Phase 2 of ICOM 5016 Project

17

Shrink wrap Software

Used by a large number of peopleLittle control on how it is usedSell at retail stored or over the WebDevelop and release it to the public

Bug fixed must be provided over Web Scales well in terms of money

License issued to individual usersShould be able to recover cost with first N licenses After that is all profit

Need to test and maintain aggressivelyTo continue selling it and making profitCreate loyal customer base

18

Customized software

Also called internal softwareUsed by people at a company or community

Smaller audienceMore control on how it used

You can actually dictate requirements for usageDevelop and deploy to the company/community

Need to give them training Often system is buggy and you need to keep fixing it

Less scale in term of profitContract-based: Once contract is over you get no moneyContracts then to be expensive (to account for profits vs loses)Contract expiries and no more maintenance is given

Unless a maintenance contract gets setup

19

Software Products classification

ThrowawayInternal code used to experiment with a given technologySometimes this is how to polish your specifications

Rapid prototype to figure out what you can and can’t do!

You want to use throwaway as a means to an end

You do not sell throwaway softwareEx. Phase I and Phase II of ICOM 5016 project

Hardwired servlet code and in-memory DB is not use againBut you get Web-based UI and organization of beans right

20

Making money on software

Shrink wrap Make a product that many people will use

Office, Photoshop, MS .Net, iWeb, MacOSCompanies: Microsoft, Apple, IBM, Adobe, Skype

CustomizedMake a product that a big agency will use

UPR PATSI, US Immigration Information System, US Postal ServiceCompanies: Rock Solid, EDS, IBM, HP

You should try to make shrin kwrap whenever possible

Only do customize to help you get cash to make another productShrink wrap is where you want to be

21

Part II: Procedural Issues

Software development is cyclic!Old school water fall software development process assures failure

You need to have constant testing and feedback from the userUML will not produce code for you!

How do I specify a multi-threaded system with a shared queue that controls access to a pool of disks?UML is good to talk with others about your code

Like ER diagramsSource code == real software specification

22

Cowboy Coding Model

You start writing code without an actual planHacker’s way of doing things

I will start writing code and I will figure out things along the way

Many ICOM Software Gurus work like thisYou guarantee that the project will be

LateFull of hard to understand codeFull of incompatibilities Full of unusable featuresFeaturing a hard to use UI

23

Waterfall Model

Software is built in stepsOne phase leads to the nextIf this phase is right the next will likely be right

24

Waterfall Model: Problems

In each phase you deal with a bunch of uncertainties

Customer changes her mind about UI You drop the ball with the design

Mixed data model with storage logicUse multi-threaded when multi-process was better

You realize your platform has buggy support for networking

Ex. PDAs!Change is assured when building software

You need a way to make mid-flight course corrections

25

Reality in Software Development

At each step you might need to revisit decisions from previous phase

26

Rapid Application Development (RAD)

Build incomplete but functional prototype (like a demo!)Debug and test major componentsInvolve customer by showing prototype

Nail down UIPrevent change of accepted features …

Add features/fixes into prototype until you reach release status

Hey, but finish the product!!!Examples:

Agile ProgrammingExtreme Programming SCRUM

27

Agile Programming

Family of techniques based uponInclusion of customer into design/developmentShort cycle to produce working code (not all features)

Every few weeks a new version with a set of new features is delivered

Test-Driven software developmentFirst make the tests, then you write code that can pass them

Refactor codeChange code based on results of debugging, testing, and user feedback

Produce stable release as results of continuous improvement process

28

Extreme Programming

Based on daily practices and team valuesCustomer and business people are part of the teamAlways deliver a new working version ASAPCommunicate effectively with all team members

29

XP Values

Simplicity Write code that is simple, clean and straightforward

CommunicationKeep direct communication between customers, developers, business people and managers

FeedbackAlways comment on out other code, features, and issues

E.g., code reviewsCourage

Write the code! If you mess up just refactorAvoid getting stuck in perfect implementation issues

30

XP Activities

Simple DesignStart with a simple system that worksAdd new working features

Pair Programming2 programmers work side by side on the same machine (like Spartan kings)Faster, better code plus you have redundancy

Test-Driven DevelopmentUnit test and full system tests as new features are added

Design ImprovementRefactoring – fix the design as you write codeYou only know you are wrong when you see it

31

SCRUM

XP can be chaotic Scrum is controlled chaosThe Team:

Scrum masterPM

Product OwnerCustomer and business people

DevelopersTeam works in sprints or burst of one month

Design, code, test and demo software Next sprint adds features to previous releaseBacklog of the spring list the features to do in each sprint

32

SCRUM Process

33

Software System Architecture

Start out by giving high level system organization

Boxes and arrows

Client Application

DatabaseEngine

Disk

34

Layered Software Design

Break down software model into layerEach layer is one or more libraries with specific role

Client API

Query Optimization

Query Processing

Storage EngineTx supp

ort

Disk

35

Each Layer is Simple

At this level you can lay down the classesUML can help you illustrate structures and relations

36

Design Patterns

Well understood and documented recipes to build software

Reusable code Idea borrowed from architecture

Archetypes Columns, arcs, etc.

Smalltalk had them for GUI Gang of Four Book (GoF) popularized design patterns for CSYou should build your libraries around them

37

Example: Abstract Factory

You need to write an email client Must run in

Windows XP and VistaMacOS XUbuntu

Each one has a different look and feelYou do not want to write the different programsInstead you want to share as much code as possible

Only differentiate in how UI elements are created

38

Example: Abstract Factory

39

Questions?