Week 9 Studio: Contract Programming

Git Repository: https://classroom.github.com/a/FOaH03Pe

Most programming work is broken up into different parts, which are usually done by different people. The first part is the specification: deciding what the program needs to do. Specifications are hard because they need to provide enough detail about what the program will need to do that someone else can program. The second part is the implementation, which is writing the main code that (hopefully) accomplishes what the specification says it should The third part is the testing, which checks the main code to see what it does and does not do, to make sure that it accomplishes what it is supposed to do.

We are going to do that today – specification, implementation, and testing – around a small flashcards app.

Today’s studio is going to be organized a little bit differently than normal. First, form groups of 2-4 people. Second, once you have a group, find another group to be your partner. Each group should have one partner group – so you’ll be working directly with the 1-3 other members of your group, and indirectly with the 2-4 people in the partner group.

For the first 20 minutes of class, your group should work on a specification. Decide what topic you want your flashcards to be about. Write the content for a few flashcards (5? 10?) compete with prompts and answers. Also, decide what you want the program to look like. What functions should exist? You will not be writing the code for this; someone else will. You are just specifying what code you want written, and what it should do once it is finished. Think about how you want someone else to write the code.
For the next 40 minutes, we will swap with partners. Your partner group will take your specification and try to implement it. They will write code that tries to do what you specified. And, conversely, you will try to write the code that they specified. They will ask you to do things differently than you asked. Your job will be to do what they asked, not what you envisioned.
Finally, for the last 15 minutes, we will swap back. You will be given a working version of what you specified. Your job now will be to test it: did they do what was asked? What works? What doesn’t? Think about both manual and automated testing as a way to figure out whether the code that you were handed actually works the way you think it should.

What follows is just advice for doing it. You don’t have to follow my advice. Do whatever you want. This is just my experience in doing this, and you might want to do it differently.

Advice

The specification is your contract; it tells the other team what you want done. The more specific you can be, the more likely you are to actually get what you want. Don’t just say “do some math problems” – how will they ever know what that means? Give them exact problems for the flashcards. Tell them exactly how many flashcards. Think about how you would implement it, and give them some structure that they can use to make it work correctly. Do you want it to count the number correct? Do you want it to be snarky? Be specific.

Remember: the partner group only has about 40 minutes to write the code. If you ask for too much, you probably won’t get it. If you ask for too little, the program will be boring and useless. Find a good balance.

Specify both program and content

The natural impulse is just to write the content of the flashcards – what questions should it ask, and what should the answers be? But that’s not enough. You are asking them to write a computer program. Be sure to also specify what that program should do. Should it be graphical (turtle) or text-based (terminal)? Should it be case senstive? Should it give the user more than one chance to get it right? Should it count the number correct? What else should it do? Anything it should NOT do?

Be Specific about Content

When writing a specification, it is important to be specific. Don’t just say “write 5 flashcards about animals.” You never know what you are going to get back. You might get back unhelpful questions suitable for little children (“what animal goes woof?” –> “dog”) when you wanted something more detailed for an adult. You might get complicated, detailed cards that only work for experts (“what kind of dog has hair instead of fur, and has complicated color genetics including parti, phantom, and solid?” -> “poodle”). You might get not-safe-for-work flashcards (you can come up with your own example here).

Also, how will you know if the other team did it right? Flashcards are intended to help someone learn a specific topic. YOU are the expert on that topic; the other team are just programmers who are doing what you tell them to. Don’t expect them to have more expertise on the topic than you do – they most likely don’t. Instead, you should provide the content, and they should just be programmers.

Think About Testing While Writing the Specification

Near the end of class, you are going to get back some code. It almost certainly will not do exactly what you expect it to – but your partner team will think it does. Think about how you will test it. As you are writing the specification, also jot down some notes about how to test it. What things will you look for? What does it mean to “work” correctly? What are some possible inputs, and what would you expect to happen with those inputs?

On GitHub, it should automatically create a repository for your team to use when programming. Great! Put your code there.

However, how will you deliver your code to your partner team, who gave you the specification? You’ll have to go to the repository on Github and add them. See if you can figure out how; ask them for their GitHub user names, then go into your repository and figure out how to add them so they can see the code once you are done working on it.

Ask for clarifications

Despite trying really hard, program specifications are almost always more vague and less detailed than you would like. As you start writing code, you start to realize all of the things that the specification did NOT specify. It is OK to ask for clarifications. “When you said X, what did you mean?” “If this happens, would it be better if the program does X or Y?” Clarifying questions are normal and good.

This is particularly important if the specification doesn’t have enough detail. If they just tell you to “write 5 flashcards about dogs”, that isn’t enough detail. Push back. Ask for details. In the implementation phase, you are just a programmer. You aren’t the designer or the context expert. If you need content expertise or design expertise, ask the other team (that designed it and gave you a specification) to do that work.

Don’t look at my studios as examples

In this course, I have provided a number of studios, each of which had a short “specification”. Studio specifications in this class are intetionally vague, to give you an opportunity to use your creativity. They don’t have a clear deliverable or end goal, and no clear description of when it is “done”. That’s intentional for this class, as it helps encourage you to build something that you personally find interesting and enjoyable.

However, this is exactly the opposite of what a good software specification should look like in a real contract situation. If you do that in a real situation, the programmer will do the absolute minimum thing possible and then collect a lot of your money for doing almost nothing. If you try to complain, then they will point to the specification and say that they did everything you asked for.

As you write specifications, don’t look at my studios as examples. Instead, think about the programmers who will implement this: they are busy, they might not be as good as you re, and they are trying to get it done quickly and easily to move on to the next project. If you don’t explicitly say something in the specification, then they don’t have to do it, and probably won’t. Don’t leave much up to interpretation because if you do, it won’t end up very good.

Is this fun?

As you work, think about what parts of this you are enjoying, and what parts you don’t. Some people really like being told what to do, and having a specification to work towards is nice and easy. Other people hate it because it feels uncreative and like they can’t express themselves. Some people really like testing because it is fun to break things and think about all the weird ways that programs get used; other people hate testing and find it very tedious and boring. Some people like writing specifications because they get to see lots of possibilities, and then get to have other people make them happen. Other people hate writing specifications because they feel like writing down all the details that a specification needs is more work than just writing the code.

Think about what parts of this you like, and what parts you don’t like. This will help you as you move forward in your career in thinking about what parts of the work you might want to do, or might want to avoid.