== Software Design ==

Design Before Programming

A computer system consists of more than just a program. As programmers we focus mostly on the software. Since we make software by typing code, programmers tend to START with typing. However, this can lead to messy, poorly planned software that either works poorly or never gets finished. It's like buying a bunch of bricks and starting to build a house without making a plan first.

A better paradigm puts the program at the end of the design process - good developers follow a process like:

• • talk to the users and find out what they need and want

  • design what the program should look like and how it should be used

  • design the modules (pieces) that will be needed inside the program to achieve the goals

  • THEN give the design to the programmers and let them implement it (write the program)

This puts the program at the end of the process, rather than in the middle or the beginning.

As beginning programmers you still don't know what is possible because you don't know the entire language yet. That makes planning and design pretty difficult. It helps to think about breaking the solution into MODULES (pieces) - arrays, files, methods and GUI components.

*** BUT DON'T START YET!! ***

Analysis Before Design

You must ANALYZE THE PROBLEM before DESIGNING THE SOLUTION (program).

Proper analysis requires investigating the problem and analysing the needs, by doing the following:

• • talk to the CLIENT(s) (intended user(s))

  • investigate the current system - probably involves paper or an inadequate computer program

  • collect stories of what is happening and what needs to be done

  • specify the data that needs to be collected (inputs)

  • specify the results that must be produced (outputs)

  • suggest automation that could improve the results and simplify inputs

  • summarize the desired goals and features

  • create a prototype - a very simple version of a possible solution demonstrating some useful features

  • show the prototype to the user(s) and use it to clarify and refine goals

In the real world of software development, analysis can be a time-consuming process and produce lots of documents. In a high school programming class we will probably do this rather quickly so that we can move on to the work of writing a program (and learning Java) - but we WILL do at least a brief analysis.

When programmers talk to the Client (user), they find that users are unclear and non-specific about what they need. They might say : "I'll be happy with anything." They might believe it, but it's probably not true. The prototype is very useful because it helps the client to focus on specific issues and to clarify the issues before the programmer wastes time producing an inappropriate solution.

Analysis and Design Models

Moving from a real-world paper-based solution to a digital (computerized) system requires significant changes. It requires the designer to think in a different way - a paradigm shift. A user might take a pencil and scribble out a mistake on the paper, or staple more sheets on when needed. Inside the computer these tasks involve obscure Java instructions operating on arrays or files. The connection between the real world and the computer program is often difficult to understand. A number of CASE tools (Computer Aided Software Engineering) exist for helping designers bridge the gap between the real world and the computer program. These tools guide the designers' efforts and help produce documents and illustrations. They may even create a prototype or generate code. But there are no tools that completely automate software production from beginning to end. Many CASE tools concentrate on documenting the analysis and design, to facilitate communication between designers and programmers. Analysis and design are still complex intellectual tasks. They are less precise and detailed than programming, but probably require more intellectual skill. As a result, analysts and designers usually earn higher salaries than programmers.

There are some standard processes for analysis and design. A few popular examples are:

• Top-Down Design (Waterfall model) - older

• UML = Unified Modelling Language - comprehensive

• XP = Extreme Programming - newer

• Agile = Teams and Users - latest

None of these have gained universal acceptance. Top-down design is the oldest of the three and has generally been rejected as unrealistic. UML is a collection of modelling strategies, with lots of support, but is probably too abstract and time-consuming for high school students (unless restricted to a small subset). Extreme Programming (XP) includes some of the simplest parts of UML (especially user stories) together with some practical suggestions (pair-programming). Extreme Programming probably comes closest to a usable system for young students, but even XP is too complex and time consuming. The system presented below is a simplified subset of XP, involving user-stories, prototypes, and user-programmer consultation.

User Interviews

Start with the user - they know more about their problem(s) and needs than the programmer. Ask them questions. Listen to their stories. Write notes for later. Ask them specific question about things like input data, automation, and output needs (including formats).

Investigate the current system. Get sample paper(s) from them if they are using a paper system. Ask them what parts of the current system are particularly good, as well as what parts of the system are unsatisfactory.

Prototype

If you are a programmer, you probably want to get started programming as soon as possible. The prototype is your chance to get started. But the prototype is not supposed to be a first "version" of the program. You probably will make significant mistakes and unreasonable assumptions. Plan on throwing away the prototype before you start on the real program. Nevertheless, writing the prototype will help focus your thinking, and showing it to the user will help focus their thinking. Thus, the prototype facilitates communication between the programmer and the user, so it is worth spending a bit of time on it - that will save you time later.

Goals (IB Speak = Criteria for Success)

Once you have a prototype, consult the user again. Ask the user whether you have started in the right direction. The prototype will probably stimulate a discussion that produces more stories and more requests. You might need to do a bit more work on the prototype and then meet the user again.

After sufficient discussion you should produce a list of specific goals that the solution should meet. This doesn't mean that you will actually achieve these goals, but the goals should be clear enough that you will not waste time by adding unnecessary features. The temptation to add extra "cool" features is called creeping featurism - this is a common cause of software projects finishing later (or not at all).

Getting from Here to There

The road from the problem to the solution is plagued with rethinking and restructuring. The user might have a pile of papers, but that does not mean that the solution should consist of a comparable collection of word-processing documents. Automation can eliminate the need for some of the human work (less input). Computer displays may summarize and present data more efficiently than the paper model. Automation and storage in computer systems often follow a different paradigm than the real-world paper systems. Spanning the gap between the problem and the solution is difficult.

Here is a very simple model that helps span the gap - it requires a table for each user story. Tell a STORY that starts with a specific need or event. Describe what the user(s) will do during this activity. Then describe what the computer needs to accomplish in response to the user.

The following stories are for a Student Sign-Out Sheet system, when the student leaves class (described here in java but could be done in Python/Tkinter: checkout.html).

Activity Stories

Enhanced Features

These are similar to action stories, but describe new features (or tasks) that could be included in the computerized system. The programmer should not invent these without consulting the user, although it's common for the programmer to suggest new features and discuss them with the user. Writing down the ideas facilitates communication with the user. If possible, it's nice to include one of these in the prototype, toimpress the user with the possibility of improvements and to stimulate other ideas from the user.

Normally the enhancements and action stories would be discussed with the user. We will skip that step in this example, using the students in this class and the teacher as simulated users.

Prototypes

There are two possible methods for creating a prototype:

• • Visual Protype (Mock-up) - a series of drawings representing the user-interface, together with some notes about scenarios with specific data and events. The drawings can be produced with a word-processor, presentation software, or actual modelling tools. Another possibility is a paper prototype - this can be written up with a pen on index-cards. Then the index cards can be flipped in a mock run-through where the designer pretends to click buttons and turns up another card to show the result.

  • Functional Prototype - a computer program that performs a few

  • of the intended functions. This might be limited to sample data (without actually saving new entries in a file). This could be written in the target language (e.g. Java), or produced quickly with a simpler tool like Visual Basic. It could also be a feasibility prototype, to test whether some intended features are actually possible (e.g. if the program should send an e-mail to alert an administrator to a problem, we might not be sure how to program this).

We will show both here, starting with a very simple functional prototype, followed by a PowerPoint mock-up.

Visual Prototype = Mock Up - click here to see all the pages: mockup.pdf

After making the overly-simple prototype above, the programmer can sit down with Power-point (or just a piece of paper) and sketch out an idea for the user interface. Notice that the arrows and explanations indicate what will happen, so just be looking through the pages the user can get an idea of how this would function.

Functional Prototype = Simple Java Program - click here to see the Java program: checkout.html

This is a very first shot at a prototype. It is not really good enough to show to a user, so you probably should make it better before talking to the user. Still, it helps the programmer focus their thoughts and shows that a better interface is needed.

Goals

The programmer and user need to agree on specific goals. Users might ask for something that's impossible - then the programmer explains nicely that they cannot do it. The programmer might suggest a really cool feature and find out the users don't want it or need it - then you needn't waste time on it. Before proceeding to write the program, you really need to write down a specific list of goals. That way you won't waste time on useless features, and you will KNOW when you are FINISHED!

Here is a brief (too brief) list of goals for the Check-Out program.

• • Class lists can be imported from the already existing scheduling program

  • Teachers can select classes easily, without typing (and mistyping) class codes

  • Students can check-out and check-in quickly, without typing mistakes

  • Computer automatically saves check-out entries (name, date, time, teacher name and class) in a data file

  • An extra module collects all teacher data into one central file each week

  • Admin interface allows administrators to easily find and review student records

  • Avoid any typing of data - make it all mouse-driven

The programmer will probably think of new things that are needed as they go along. For example, it might be necessary to save data immediately, directly to disk, rather than only saving at the end of the class. Or, what happens if a teacher forgets to shut down the PC in one classroom when they go to a different classroom to teach - will that wreck the data-file? Programmers must worry about dozens of "issues" like these, but it's hopeless to completely specify ALL requirements and behaviors of the program. Young students should concentrate on the goals that are important and meaningful to the end-user(s).

Analysis Finished

That was the end of the analysis stage. In a real program (or an IB project), the design stage comes next. Here is an overview of the IB expectations for the Internal Assessment Project.

** Key Concept - produce GOALS during Analysis, and keep looking back at them in later stages ***

You'll see we did a pretty good job on the analysis (though we "faked" some of it). Since you're still learning Java, we will mix the design and programming together (not a good thing for more experienced programmers, or large teams of developers). When you get to the second year of IB Computer Science, you'll be ready to do a proper design before programming.

Why Documentation?

You might notice that the stages of the software life-cycle form a complete circle, returning to the starting point. This happens because most systems require reworking after they've been used for a while. You see different versions of commercial software, released every couple of years. If our Check-Out program actually gets finished and used, it may need some improvements after the first year of use. Or there may be some significant system changes (e.g. a new Operating System or new hardware) that require changes in the program - for example, what if it needs to run on a tablet or Smartphone? Some small changes can be done as "patches" - e.g. renaming the server might require a very small change in the program. Other changes - like a different schedule of classes - may require significant rewriting of the program code.

Documentation is an attempt to write down all the original thinking and information required for later changes. Without internal documentation (comments in the program code), a new programmer may have severe difficulty changing a 5-year-old program written by someone they never met. User-documentation is especially important when new employees are hired (new teachers or new administrators). Computer systems without documentation are almost certainly doomed to drastic failure over the long-term. Cars don't run forever without maintenance, and neither does computer software.

Knowing that software has a "life-cycle", including maintenance and revisions, makes things a whole lot easier for designers and programmers. It means you don't need to produce a "perfect" product the first time through the development process. Some issues can be postponed for later versions. This doesn't mean you can release a defective product (it does need to work reliably), but it does allow you to release a less-than-perfect, somewhat incomplete version. And in the real world, the reality of the software-life-cycle keeps programmers and designers employed - certainly a good thing for them.

Beware Creeping Featurism

Programmers must avoid the temptation to add more cool features as they write the program. They need to pay careful attention to therequirements and goals produced by the designer(s). Programmers must concentrate on meeting the written goals and debugging any problems that cause the goals to fail. In the end, the user(s) will expect the program to run reliably and efficiently. They probably won't thank the programmer for the useful tool they produced. Programmers might think that the users will get excited about really cool features, but those are no substitute for functioning software. Adding new features usually increases development time. They make the solution (program) more complex and introduce new bugs. Good programmers avoid this temptation and concentrate on getting the basics right.

What now? Start programming?

We will assume that the very brief analysis presented above is adequate and that the stated goals are sensible. Let's start programming!! ..... no, wait just a minute. We still need to do some more design. We could go ahead and program the mock-up user interface shown above, but there really has been no serious thought given to the data file storage requirements.

The analysis should have dealt mainly with the problem, with a bit of forward-thinking about possible solutions. Now the design stage involves thinking about the overall structure of the solution, with some forward-thinking about how to write the program. Once again, a prototype program might be useful to help us focus our thoughts. But be warned!! IF you go down this road, writing code to see what works and what doesn't, you will probably make lots of false starts. You will probably throw away lots of code. You will probably add stuff you don't need and regret it later.

Use the design stage to spend time thinking about how to make the programming task as simple as possible. We will look at possible designs (very brief) to see how a bit of forward-thinking can save time in the long-run.

Project Overview

This diagram illustrates the central importance of GOALS and TESTING.

==========================================================

Structural Design

Data Files - External Storage

The mock-up ended with a page describing the data-flow between data-files.

This indicates that the following data-files should be created:

• • Class-lists for each class, probably organized by teacher, like this:

  • Frizzle, F TOK 11 History 9a History 9b ... more ...

  • ------------- ------------ ------------- -------------

  • History 9a Adams, A .... ....

  • History 9C Baker, B .... ....

  • IB Geog 1 Charles, C more student names

  • IB Geog 2 Duke, D .... ....

  • TOK 11 ....

  • Zorro, Z

  • Data files for each teacher containing check-out records:

  • Frizzle, F - checkouts

  • ------------------------------

  • TOK11 15.03.08 09:10 09:20 Charles, C

  • TOK11 15.03.08 09:15 09:35 Backer, B

  • TOK11 15.03.08 09:25 09:35 Zorro, Z

  • History 9a 15.03.08 09:50 09:55 Williams, W

  • TOK11 16.03.08 11:15 11:20 Duke, D

  • ......

  • Central master file containing all records for all teachers for one week

  • It looks just like a checkout file for one teacher, but with the teacher's name addes on the front of each record

  • Master File

  • -----------------------------

  • Frizzle, F TOK11 15.03.08 09:10 09:20 Charles, C

  • Frizzle, F TOK11 15.03.08 09:15 09:35 Backer, B

  • Frizzle, F TOK11 15.03.08 09:25 09:35 Zorro, Z

  • Frizzle, F History 9a 15.03.08 09:50 09:55 Williams, W

  • Frizzle, F TOK11 16.03.08 11:15 11:20 Duke, D

  • Brown, A Math SL 1 15.03.08 11:25 11:29 Charles, C

  • Brown, A Math SL 1 15.03.08 11:30 11:35 Duke, D

  • Brown, A Math SL 1 15.03.08 11:32 11:40 Fritz, F

  • Brown, A Math 9d 15.03.08 13:20 13:35 Williams, W

  • ....

There are other possibilities for organizing the data. For example, we could try to keep all the data in one single file all the time - that is, write each check-out record directly into the central master file. Since there are 100 teachers, we would need to ensure that simultaneous access is possible. This generally causes problems in data files and requires some more sophisticated programming techniques than we have studied so far. So we should stick to individual files for individual teachers. The weekly collection process that uses all the teachers' files as input can run on the weekend when none of the teachers have the files open. This avoids the simultaneous access problem.

Arrays - Internal Storage

The checked-out student names must stay in a list temporarily until they return. It is not possible to write them immediately into the teacher's data file when they check-out, because it won't be possible to add the check-in time afterward.

The simplest solution is to keep the check-outs in an array (or arrays), update them when they return, and then write the entire list into the teacher's file one time at the end of the class.

It might be possible to keep this in a String array, with an entire record stored in a single String, like this:

info[0] = "09:10 09:20 Charles, C"

into[1] = "09:15 xx:xx Backer, B"

But when a student is away, the String must contain xx:xx or some other place-holder until the return time is entered. This sounds a bit complicated to program.

A better solution is to use parallel arrays to store the data, like this:

leave return name

------- ------- --------------------

[0] 09:10 09:20 Charles, C

[1] 09:15 Backer, B

The entry in the return array can remain blank until the student returns.

Algorithms (Methods)

We will need to write methods for the necessary tasks, like:

• • reading all the names for a class from the class-list files

  • moving a name from the class-list to the check-out list

  • adding a name to the leave/return/name arrays

  • getting the current time from the operating system

  • saving all the check-out records into the teacher file at the end of a class

  • weekly collection into the central master file

  • search for a name in the array to record the return time

  • search for all the records in the master file matching a name (for admin)

  • .... lots more ....

A good design would include a complete list of methods. We will start with this list, do some programming, and add needed methods as we go. But remember, this is NOT the right approach for experienced programmers - we will change to the right approach later, after learning more Java.

Software Design Summary for Analysis/Planning Stage

Considering all the ideas (above), the following Design Summary should help with your project.

1. Select a Client (intended-user)

and a Problem that is important for the Client.

2. Interview the Client.

Discuss the Problem.

Collect sample data.

Take pictures (if appropriate).

3. Write USER STORIES.

4. Discuss IMPROVEMENTS that can be obtained by AUTOMATION.

5. Create a VISUAL PROTOTYPE. This includes possible USER INTERFACES

and, if possible, some INTERACTIVE (clickable) items.

If you wish, you can produce FUNCTIONAL PROTOTYPE

with the same user interface(s) and some functioning Buttons.

6. Discuss the VISUAL PROTOTYPE with the Client.

Take notes, recording requests for changes and improvements.

7. From the USER STORIES and VISUAL PROTOTYPE,

produce a set of GOALS (Criteria for Success).

That is the end of Stage A. Notice that there is no programming

in this section (except the optional Functional Prototype).

Functional Prototype

Many students are uncomfortable doing so much work without

writing a program to check whether their ideas might work.

A FUNCTIONAL PROTOTYPE is useful for three purposes:

1 - show the Client what the finished program might look like

2- help the Developer to be sure their programming ideas will work

If you do make a FUNCTIONAL PROTOTYPE, do it QUICKLY!

You are not writing the actual program - just a very rough "first draft",

to work through some of your ideas.

Plan on throwing it away - or at least most of it.

That being the case, you can take lots of short-cuts.

Work quickly and don't worry about small details.