HW1: Software development difficulties

(With credit to Michael Ernst for this assignment.)

Reflect on your software development experience. Oftentimes it is lots of fun, but at times it can be frustrating.

1. Think of a time when some problem took you a lot of effort. Be specific: choose a concrete incident that you remember. It should not be trivially solvable by an existing technique or tool. (Don't believe that existing tools would solve all your problems, even if they claim to do so. They might only address part of your problem, or they might have poor usability, or they might have other limitations.) It should not be merely due to your ignorance or inexperience. (But, some tools can help you more rapidly learn facts or overcome inexperience. Don't believe that all problems you have had are due to your ignorance or inexperience: they are not!)

If you cannot remember a specific incident, then put the assignment aside, think about it in the background, and come back to it later. If you still can't remember anything, you might want to look through the history of commits in projects you have worked on, or issues opened and closed, or code reviews, or TA comments.

After your name (which should be on all assignments), write 1/2 to 2/3 page discussing the problem. Give it a descriptive title. Write about the same amount of text on each of the following:

Describe the problem in sufficient technical detail for others to understand why it was difficult. The topic sentence (that is, the first sentence) should be an informative summary or description of the problem.
Describe what methodologies and/or tools you used. Be specific about ways in which they were helpful and ways in which they fell short.
Search for a tool or methodology that would solve your problem.
- If one exists that completely solves your problem, you have learned something valuable, but don't write up that problem; start over at the beginning and choose a different problem to write up. (As noted above, beware believing all tool/methodology claims.)
- If no tool exists that solves your problem, then describe the tool or tools that come closest to solving your problem, and explain how it falls short.
Propose a tool that would solve your problem. It might be similar to, or completely different from, the one that you described above. Describe at a high level how it would work. Think about the challenges of building and deploying such a tool. Why do you think no one has built it already?
When thinking about how the tool might work, one approach (but not the only one) is to start with how programmers solve it by hand. What data do they use, and how do they use it? Whenever a task can be done manually, an approach to automation is to dissect and understand the manual process, and see whether some of the parts can be aided mechanically. Even if you don't solve the entire problem, automation can help programmers by performing one step. Don't get discouraged if some task is impossible. Often there is a different way to solve the underlying problem that programmers care about, or there is a special case that is tractable. Even approaches that seem impossible at first may help you better understand the problem.

2. Do the same thing, but with a different problem and solutions. Choose two problems that are different from one another; for example, they shouldn't both be about any one activity/topic, such as requirements, coding, testing, debugging, performance, documentation, etc.

3. At the end of the document:

List people or resources who helped you with this assignment. (You don't need to mention web search, which you should definitely use.)
How many hours did you spend on this assignment?

Submit a two-page PDF file. Use a font size of 10 or 11 points, and standard margins (about 1 inch).

This assignment will reward careful thought about interesting problems and issues. Please introspect deeply and thoughtfully about software design, development, and maintenance. Doing so will help you in this class, and beyond.

Tips

Here is how to avoid some common problems that past students have had with this assignment.

Write your name on your homework
Be specific: The most common reason for low grades on this assignment is lack of specificity. The assignment asks for specific events in your life, not general descriptions of an abstract problem. For example, don't merely say, “When writing tests, it is hard for me to figure out all the corner cases”, or “A common problem in C programming is segmentation faults”, or even “During my summer internship I spent a lot of time trying to read and understand ambiguous documentation.” Give enough details to understand the problem; don't describe it vaguely. Also give concrete specifics about how the tools or methodologies you used were useful or not.
Discover the underlying problem: Sometimes it is easy to get tunnel vision and to get fixated on one particular approach. Think about the underlying problem you were trying to solve, in addition to the specific way you were trying to solve it. Is there a different approach to the problem that would be more effective? Try to think outside the box.
Support your claims: Don't say “Current techniques are not mature enough to do it,” without explaining why. List and briefly describe current techniques, and explain why each one falls short.
Avoid trivial problems: Avoid discussing implementation annoyances unless you can identify an underlying principle. (Example: “Windows (or Unix) lacks this feature that Unix (or Windows) has,” or “My favorite tool does not support X.”) Avoid mentioning difficulties in performing tasks that don't matter. (Example: “I can't determine the cyclomatic complexity of my Tcl code.”) Avoid problems that are extremely minor or that can be solved easily. (Example: “I often fail to balance delimiters before attempting to compile a file” or “There should be a public forum where people can ask and answer questions about tool X”,)

Showing example code may be helpful, but is not needed for every writeup, not even all those about issues with code.