HW 8: Technical writing

CIS120 Homework 8: Technical Writing in Computer Science

Due 5:00 pm, Sunday, April 20 (initial version due; note: no late submission)
5:00 pm, Monday, April 28 (final version due)

File to submit: essay.doc or essay.pdf

Overview and Motivation

So far, we have focused on computer science ideas and programming techniques. However, we have not focused on how to effectively describe those ideas in writing. Therefore, your next homework is a writing assignment. Why are we asking you to write in a programming course?

So that you will be a better (technical) writer.
You will have to do some technical writing someday, in some form: perhaps in technical documentation, a research paper, or a software blog. You aren't going to get the experience of writing about programming in your English class. It has to be here.

So that you will be a better programmer.
Too often programmers stop development too early. But, just as you shouldn't turn in your rough draft of your essay without revision, you shouldn't declare your program finished just because it produces the right answer. Good programmers modify working programs to improve their structure, clarify their exposition, and increase the maintability of thier code.
So that you will gain a deeper understanding about programming in Java.
To really understand an idea, you have to write about it. Writing will expose the gaps in your knowledge and force you to think more deeply.

The Assignment

Your assignment is to write an essay that gives advice about programming in the Java language. Your advice should be based on some programming pattern, concept, idea, or technique that we have discussed in class. There are no fixed guidelines about the format of your essay, but it should contain the following components. It should:

Describe your advice, first using specific code examples and then in general terms
Argue why your advice is good
Explain where it is applicable (with examples)
Discuss trade-offs and comparisons with other approaches

An example of the sort of essay that we are looking for is an excerpt from the book Effective Java by Joshua Bloch, "Item 9: Always Override toString." You can think of your assignment as to write a section of this book.

For inspiration, you may use some of the section titles from Effective Java:

Item 1: Consider providing static factory methods instead of constructors
Item 12: Minimize the accessibility of classes and members
Item 14: Favor composition over inheritance
Item 16: Prefer interfaces to abstract classes
Item 23: Check parameters for validity
Item 24: Make defensive copies when needed
Item 27: Return zero-length arrays, not nulls
Item 34: Refer to objects by their interfaces

Alternatively, you may discuss other ideas presented in lecture. For example:

Separate the model, view and controller functionality of an application
Use generics in classes and methods to encourage reusability
Use iterators for accessing lists and sequences
Rewrite tail recursive methods using while loops
Use a binary tree to store ordered data

Some of these topics we have covered explicitly in class. For others, you may need to think hard to figure out what they mean and why Bloch suggests them. You could, of course, go to the book, read the section and copy Bloch's essay as your own, but that would defeat the purpose of the assignment. The point of this assignment is for you to reflect on what we have covered in class as practice your writing.

Audience

The intended audience of your essay should be a general, computer-science-educated audience, such as your classmates. You can assume that your readers are familiar with the Java language but are not experts. For example, you can assume that they know what a "for" loop or a method is, but you should explain technical topics that are specific to Java, such as generics or nested classes.

Length

Submit an essay that contains at most 1,000 words (this length works out to 3-5 pages at 250 words/page). There is no minimum length requirement; the paper should be exactly as long as it needs to be to make its point. Shorter is often better. The limit of 1,000 words is a guideline of how much detail your paper should contain, and it is not that much at all. In fact, you may find it difficult to write only 1000 words about your topic. To do this assignment right, you should first write a draft which may exceed the 1,000-word limit, and then you should spend time cutting it down. But that effort will be worth it: Concise writing is more clear and more powerful than wordy prose.

Your submission should either be a Microsoft word file (essay.doc) or a pdf file (essay.pdf) created with some other word processor.
(Note that if you have Word 2007/8, you'll probably have to make sure that you save the file in "Compatibility Mode" so that it uses the doc format instead of docx.)

Plagiarism and Research

You may not plagiarize. This means copying any piece of text directly from any other source (such as Effective Java, wikipedia, a Java textbook, etc...), including ideas without attribution, or getting someone else to do the writing for you. You will get caught, and you will have to face the Office of Student Conduct.

However, you may research your topic, using any source other than Effective Java, and refer your al sources in your essay to substantiate your points and provide credit for ideas. If you do so, your assignment must include citations for these sources. (These citations are not included in the word count.) To format these citations, you must use the style specified by the IEEE Computer Society, see Section IV D "References" pages 4-5 of Information for Authors.

You can find resources for researching these ideas at SEAS Library's "CIS120 - Information Resources in Computer Science"

Evaluation

We will grade your essays in two stages. You will receive feedback on your initial submission during lab the week of April 21. The writing fellows will be using this checklist to give you suggestions. After that, you should rewrite your essay based on that feedback and resubmit it on the last day of classes.