CSCI E-168

For the Final Project itself: A few high-level suggestions

• “What is the simplest thing that could possibly work?” (Kent Beck)
• “Don’t Repeat Yourself” (DRY – Dave Thomas and others)
• get it working first
• use good taste (if you get your code working, and it looks like a hairball, see if you can make it more understandable)
• Don’t forget it’s Ruby; write like a Rubyist

About the Writeup

The final project writeup is much like the final project proposal, except that you can reflect on what you have done, and quote code, as appropriate.

The best writeups describe the application in terms of what the user experiences, and then in a separate section, explain how it was done. In other words, the writeup typically has two sections:

• Use Cases
• Implementation

The easiest way to write is to think about your intended reader. For the use cases, the reader is someone who needs to know what is going to happen. The use case is essentially the “story” of the user experience, using the vocabulary of the application (For the “Publications” application: Publications, Annotations, Tags, etc.), just as we did for the assignment overview, and you did in your final project proposal. That reader might be someone in QA, a VP of marketing, or someone who is evaluating your product.

For the implementation section, the intended reader is another developer. Explain to that reader what they need to know to understand, maintain, and modify your code. I am sure that you have read documentation for software packages that seems either too wordy or too skimpy, or that somehow leaves out key information, or buries it where it is hard to find. To describe your implementation in a usable way, you need to get outside of your own head a bit, which is hard; but even though it is hard, you need to develop this skill.

In the implementation section, you’ll recapitulate your discussion of the MVC components and the “features” from the proposal. But here you’re able to to be much more precise (because you implemented it), and help the reader to the key information that will make for easy understanding and maintenance. Do not forget to include any information that is needed to test your application: For instance, if there is special setup required to get e-mail working, include that information. If you had to use an unusual fork for a gem on Github, include that information. Again, think about what your questions would be when given a new app to maintain.

Regarding internal documentation: We do not require you to generate “rdoc,” but you should provide a comment on public modules, classes, and methods. Classes take “responsibility” for aspects of your project, so it is appropriate to use that kind of language:

# The User class is responsible for managing data pertinent to the User:
# the email address, username, first name, etc.
class User < ActiveRecord::Base
# (implementation left out)
end

Public methods deserve clear but brief explanation, too. Private methods that are used by more than one other method usually require some explanation, because they are attempts to keep your code DRY. Another kind of method that frequently needs documentation — because it will stump a new developer — is any method of more than 10 to 15 lines (many would say that for Ruby, the need for clarification emerges after 4 or 5 lines). The reason for this is that once the code extends beyond 10 or so lines, the method name itself will typically end up being so generally that it doesn’t really explain what is going on. So you need to help your reader.

Your writeup is also key to evaluation. Oftentimes your grader cannot see what you’ve done unless you tell the grader. So don’t forget to “crow” about the compelling nature of your implementation and features and the power of your implementation.

Regarding the writing process, a former TA had this to say: if you have a hard time figuring out how to write something of use to another developer, imagine telling someone in section how to do what you did, or complaining to them about all the things you had to try before you hit upon the thing that worked. Especially where your code is a little hairy or obscure, you want to explain why you did it that way instead of some other way that the other developer thinks, on first glance, would have been better. If the actual reason you did something was “I didn’t have time to do this any other way,” that’s still valuable information to provide, as it allows the future developer to distinguish between necessary and unnecessary complexity in your code. If you do not point out unnecessary complexity in your code, we will assume that you did not notice it, and from a grading perspective it is worse to do something nasty and not notice it than it is to do it and admit it. (Of course, it may just make sense to point out nasty bits in inline comments; not everything deserves a mention in your writeup itself. The point is not to leave ugly or ’smelly’ code in your project and hope we won’t notice it.) Think of your writeup as writing the first part of a good story about your project. You want the reader (QA, potential users, future developers, etc.) to be engaged, informed, sympathetic, and eager to be involved in the work of adding on to the story.

This TA continued: You don’t want to write a sentence, run a word count, write another sentence, run another word count, and so on until you reach some magical length. If you tend to save the writeup until the very end and then sit staring at a blank screen wondering what to say, try keeping a log while actually at work on the project: jot down problems you’re facing, decisions you come to and why, expressions of frustration, notes about how long something took you to do, resources you found helpful, etc. Then when you get to the writeup you will have a wealth of raw material to use.

Final Project Checklist

1. Double-check that your code is using Rails 2.3.3 (see config/environment.rb); and, of course, Ruby 1.9.1.
2. Use “rake package” to create your ZIP; if that doesn’t work, ZIP up your project by any means necessary.
3. The writeup should be in the root at student-writeup.txt, .pdf, or .rtf; and . . . for the writeup . . .
   1. Remember that the writeup is a significant part of the grade. There are some tips here: http://e168f09.plugh.org/assignments/assignment-note-tips-for-the-final-project-and-the-final-project-writeup/2. Are there any config issues (e.g., e-mail setup) that need to be described in the writeup and/or edited in the code? If so, describe them completely and clearly, so that your TA can be set up properly.
   2. If there are any 3rd-party APIs or other resources for which one needs a key, provide the key.
   3. Are there any required gems? Make sure to list them, along with the version numbers you’re using.
   4. Provide “use cases” in the FP writeup that are detailed enough for your grader to reproduce the use case.
   5. If you have a chronic exception or problem, report it in your writeup.
4. Is the Ruby code Rubyish? (indentation, using braces for single-line blocks, do/end for multi-line, etc.)
5. Remember that we prefer to keep code to a minimum in the views. Ideally, your controllers are “thin” as well, for operations that involve updating models.
6. Verify that migrations run; the grader should be able to run all migrations from scratch.
7. If you generated your controllers, models, and views with “script/generate scaffold,” remove any controller actions and views that aren’t being used.
8. Do manually exercise/test your whole app — we commonly get submissions where supposedly things work, but the handed-in code doesn’t work in some of the simplest use cases. If there are parts of your app that worked before but are now breaking, at least document this in your writeup so that we know. Otherwise, we will waste a lot of time trying to figure out the extension of the issue.

“A nice to have”: Include screenshots of the “home page” and an interior page.

A very small number of you (perhaps 2 or 3) received permission to use components that were outside the scope of the course (for instance, MySQL or PostgreSQL), and are running your apps in EC2. We strongly suggest that you get your TA’s public key. Then log in to the ubuntu user, and go into the .ssh directory. Append to (or create, if necessary) a file called authorized_keys — then put the text of your TA’s public key into that file. Ask your TA to verify that they can log in to your instance. I think that those of you who are using EC2 this way know some of these details already, so I won’t belabor them; but if you need extra help, e-mail your TA and me.