When writing a specification for your project, reference the template below. Each section includes a description of what the section should include, plus examples within a quote, like this:
Example specification
A brief description of what your program will accomplish. The goal is not to describe every feature of your app, but to provide some context for the rest of your specification. For an idea of how long it should be, imagine you're walking from one class to the next, and your friend asks you what project you're working on in Programming class.
Mr. Sommerer and I will be writing a calculator app. We plan to start by implementing addition, subtraction, multiplication and division, as well as decimals and positive/negative numbers. We'll design a user interface for it using the Qt framework that looks similar to the Windows calculator app in standard mode.
Start by brainstorming a list of features your app can have:
- Show result of current calculation
- Add numbers
- Change sign of numbers
...etc
Next, look through the list of feature ideas and split the list into features your app absolutely has to have, and features that might be interesting but not necessary. Use your own judgment on this. The idea is to save yourself some time specifying features that you might not end up implementing.
Initial Features
- Show result of current calculation
- Add numbers
- Flip the sign
Optional
- Square a number
- Memory support
- Add thousands separator to numbers
Finally, modify your list of initial features to describe how the feature should work from a user's perspective.
As much as possible, try to think through different edge cases for the features. If you have more detail here, it will be easier to write different parts of the app without needing to talk with each other, and it will be easier to design your classes and estimate how long features will take.
A good rule to keep in mind is that for any questions that come up while discussing a feature, you should write down the answer in your feature list.
Initial features
Display
A text box should display the result of the last calculation or the current number being entered. If a number is negative, a - should be displayed to the left of it, else none should be displayed.
Numbers
General case: Clicking a number button should add that number to the right side of the current number in the text box.
Edge cases: If the current number has 16 digits, pressing a number does nothing. If the last button pressed was an operator, like + or =, pressing a number should replace the contents of the text box with that number.
Change sign
General case: Clicking the sign button should make the current number negative if positive, else make the number positive if negative.
Edge cases: If the current number is 0, clicking the sign button should do nothing.
Optional
- Square a number
- Memory support
- Add thousands separator to numbers
To support the list of features, add some images of what you expect each screen in your program will look like. These exist to visually describe how interactions will work rather than how they should look, and so should be low-fidelity. Paper or MS Paint are fine.
Write some class diagrams based on your list of initial features, like we've done in class. Text or pictures are both fine. We're interested in classes that make up your program's logic here, more so than interface-related classes.
Calculator class
Fields
- currentValue: number - The current value being modified
- lastValue: number - currentValue gets saved here when an operator key is pressed
- operation: None/'add'/'subtract' - The operation to perform on next evaluation
- operationPressed: boolean - True if the last key pressed was an operator key
Methods
- add - sets the current operation to add
- signChange - flips the sign of currentValue, unless currentValue is 0
- number(num) - adds 'num' to the 1s place of currentValue, pushing other numbers to the left
- evaluate - performs 'operation' on currentValue and lastValue and sets the result in currentValue
Once your spec is approved, we'll use GitHub to break the features down into units of work and plan how long we expect them to take. GitHub has an Issues tab that functions like a task list, and makes it convenient to keep track of what needs completing.
First, create some milestones on GitHub for your project. They're under a Milestones button on the Issues tab. Milestones function as checkpoints to help you prioritize work and show progress to your clients (teacher) throughout the project. Mr. Sommerer might have a better idea what days would work well for deadlines, but I'd suggest the first class day after weekends so you'll have some time to finish everything.
After that, go through your list of initial features and create issues on your GitHub repository for them. You might need some non-feature-related issues as well, like for creating the initial structure of your project or writing tests. As you create issues, assign them to the milestones you've created. As far as how to write issues, your goal should be for someone to be able to load your GitHub repository and pick up an issue to work on without having to ask you how to implement it.
Once you're finished creating issues, you can go through the issues in your first milestone and assign them to who plans to work on them.