This coursework is structured into three parts:
1. Preparing to code read/overview of the system
2. Navigating and locating specific functionality
3. Reflection
Ideally, you will complete Part A before you even read the text of the remaining parts, and certainly before you begin to attempt them. This will ensure you experience the benefits of these code reading techniques to the maximum extent, and will also help you write convincingly about those experiences in your answers to Part C. Otherwise, you can attempt the exercises in any order, although you will probably find it easiest to work through them in the order given here.

Tool Support
The description of this coursework assumes that you are using a recent version of Eclipse as your development environment. However, you are free to carry out the work in your preferred development environment, provided that you understand that technical support is only provided for students using the School's installations of Eclipse. If you use an alternative environment, it will need support for access to CVS repositories, the ability to perform text searches over several different projects and support for navigating between the directories and files in multiple projects. Specialised support for JavaScript code is of benefit, though is not essential.
Do not worry if you are unfamiliar with JavaScript. Any Java programmer will recognise enough of JavaScript to be able to interpret the code sufficiently precisely for the purposes of this coursework.
Part A: Getting Started
In this part your prepare you mind for what you might find, check out some source code and determine the high-level structure of code.
Section A.1: Preparing Your Brain to Read Code.
You will examine the source code of a well-known open source e-mail client. Since this is a large system and you are familiar with the broad functionality of e-mail systems, you must use a top-down approach to locate specific functionality. In this approach knowledge of the domain is used to extract maximum information about the system from a high-level view over it. Therefore, the first step is to prepare your brain for the code reading by thinking about the kinds of functionality you would expect a mailer to provide and the sorts of design components you would expect to find within the code itself.
First, using your knowledge of how mailer programs work in general, list the actors that a typical e-mail client must interact with. For each actor, give its name and a brief (one or two sentence) description of how it interacts with the mail client.
Thinking about the e-mail clients you use yourself, make a list of all the user stories/use cases you expect such a client to implement. Start with the standard functionality (e.g. “Send a message to a named recipient”) and move on to more unusual, or less frequently used, functionality. If you give your answer as user stories, you only need to give the functionality, and can omit the user roles and business values. If you give your answer as use cases, you only need to give a short phrase, such as would be suitable as the name for a use case (e.g. Send Message), rather than giving any detailed description of the use case behaviour at this stage. Hint: You may find it useful to fire up your own mailer and play with its functions to gain inspiration for your answer.
As well as generating some expectations about the kinds of functionality you would expect an e-mail client to implement, you should also generate some expectations about the likely technologies and design decisions that you could encounter when you examine the code. This will help you when reading, as you will be able to recognise key features more easily when you encounter them.
Finally make three diverse predictions about the internal organisation of the system you will encounter when you start to read the code. The predictions could refer to architectural organisation or components that you would expect to see, particular technologies or languages that you might encounter, or different design options that could have faced the original designers.
To give you an idea of what is required, an example prediction might be:
“The e-mail client must have some way of reading and writing files to the user's local file store, so I would expect to see some component that manages this, in a way that allows multiple operating systems to be catered for.”
Section A.2: Checking out the Source Code.
Now that you have prepared your brain for code reading, you are going to look at the code itself. The mailer you are going to use as the basis for this exercise is the Thunderbird mailer, which is part of the Mozilla project.
All the Mozilla source is publicly accessible from the project's CVS repository. (The Mozilla project changed a couple of years ago to use the Mercurial version control system, but older versions of the code are still accessible from the CVS repository. Your are going to stick with the CVS-accessible code for this exercise because CVS access is built-in to many standard IDEs, which is not yet the case with Mercurial.)
To check out the Thunderbird source code into Eclipse from the Mozilla CVS repository, follow the sequence of steps below:
1. Start up Eclipse.
2. From the Window menu, choose Open Perspective→Other→CVS Repository Exploring.
3. From the toolbar of the “CVS Repositories” view, select the “Add CVS Repository” button. (Hover the mouse over each of the toolbar buttons in turn to find out which one this is. It looks like a small database with a "+" symbol superimposed on it.)
4. Enter or select the following values in the form that appears:
o host: cvs-mirror.mozilla.org
o repository path: /cvsroot
o user: anonymous
o connection type: pserver
o port: default
o No password is needed for anonymous access to this repository.
5. Press the Finish button to create the link to the Mozilla repository.
6. The repository will appear in the “CVS Repositories” view as a tree view. You can examine the repository's contents by expanding the tree view. However, in order to get more convenient access to the files, you are going to check them out into an Eclipse project. Open up the HEAD branch, and find the directory called “mail” within the "mozilla" directory (NOT one of the MozillaSource* directories). Right click on this directory and request “Check out”.
7. This will create a new Eclipse project called “mail” to be created within your Eclipse workspace. Change back to the Java perspective (Window→Open Perspective→Java or use the toolbar at the top-right of the Eclipse window) to verify that this has happened.
8. The Thunderbird development project Web page tells you that the Thunderbird code lives in four directories: mail, mailnews, chrome and toolkit. Repeat the “check out” instructions above, until you have checked out all four of these directories into your workspace.
9. Change to the Java perspective and close any other Eclipse projects you may have created, so that you have only the four Thunderbird projects open.
You now have the code checked out, and your top-down code reading can begin. First, use the top-down reading technique to generate hypotheses about the roles of these four projects (chrome, mail, mailnews and toolkit) in the implementation of the complete Thunderbird functionality. To generate your hypotheses, you should look at project names, directory names, directory structures, file names, and any readme files, makefiles or other overview files likely to provide a high-level view of what the code is doing. Try to resist looking at the actual code at this stage.
For each project directory, give your hypothesis as to its role in the overall Thunderbird functionality (1 mark per directory), plus a brief justification in terms of the evidence you found in your examination of the high-level structure of the code
Section A.3: How does it do...?
The previous exercises have got you thinking about how mail clients like Thunderbird do their work. At this stage as you have only just begun to explore the code, should have a lot more questions than answers. List three questions (or groups of related questions) that have occurred to you about any aspect of the Thunderbird functionality. For example, you might ask:
Does Thunderbird do any checking of e-mail addresses for validity, before sending messages? If so, how does it make that check?
To receive full marks, questions should be specific rather than vague, e.g. 3 questions at the level of “How does it send a message?” will earn very few marks.
Part B: Finding and Reading Specific Functionality
Next, you are going to hunt down the code which implements the sending of mail messages. As usual, you will begin by bringing to mind your existing knowledge of send message functionality, to prepare your brains for recognising the functionality you are looking for. We will use a mixture of top-down and bottom-up reading strategies, as the task demands.
Section B.1: Preparing the Brain to Code Read
Using your general knowledge about e-mail clients and servers, and the process of sending e-mail messages, write an outline of the behaviour that an e-mail client must implement, in between the user requesting a send on a completed message and the message leaving the control of the mail client program. The outline can either be written as pseudocode, or as an English description.
Most of you will probably have some gaps in your knowledge about what happens inside a mailer when a Send request is issued. List 3 questions that are raised by your attempt to outline this behaviour. If you included questions about sending messages in your answer to Section A.3, the questions given here should be more detailed and precise.
Section B.2: Using Keyword Search to Locate Functionality
Next, you are going to look for the code that implements the sending of a mail message. Keyword search is a good place to start, when you do not have a clear idea of where the functionality may be located. A file search across all four projects on the keyword “send” results in 5145 matches – too many to examine individually.
Close all projects except for the mail project, which is the focus of this exercise. Propose 6 alternative keywords that you could search for that might give more useful, focussed results than the full “send” keyword search described above. Try them all out, and give the number of results found for each one.
Based on these numbers, and an examination of the file names which contain the matches, which of the keywords you proposed give you the most useful results in terms of telling you where the implementation of sending a message might be located? Based on this, give a concrete hypothesis as to which file or files you should examine in order to discover how Thunderbird goes about sending messages. Explain what features of the matches/matching files led you to propose this hypothesis. Be careful to give the full path names of all files mentioned in your answer, so that there are no ambiguities.
Section B.3: Bottom-Up Reading of Located Code Units
Your investigations into the matches found in Section B.2 should lead you to discover four main functions connected with sending of e-mail messages. Give the names of these four functions, stating clearly the full path of the files in which they are defined. Examine the code of each function and then explain briefly the functionality it implements and its role in the process of sending e-mail, making clear the differences between each of the functions.
Note: if you were trying understand the full send-message behaviour, you would have to explore code in the mailnews project, but this is not necessary to receive full marks for this exercise, which is about practicing making decisions about code in the absence of the full information. So, try to confine your reading to the mail project if you can, but if you get really confused and stuck, looking at some of the mailnews code might help.
Section B.4: Auto-Saving of Mail Messages
Continuing to focus only on the mail project, locate the function that handles auto-saving of mail messages during composition. If your IDE has an Outline View for Javascript files installed then you will find this the most useful way to locate the function, especially if there is an option to sort the function names alphabetically. If you are using an IDE installation that does not have such a view, you can simulate a close approximation by doing a search for the keyword “function” on the files you are interested in. A search on “function *keyword*”, where “keyword” is replaced by some term of interest, can also be useful.
When you have found it, examine the body of the function. You should see something that raises questions in your mind about how auto-save is handled by Thunderbird. List these questions.
Examine the functions called by the function you located above, to see if you can find answers to your questions. What new questions are in your mind after this deeper examination? What hypotheses can you make about the behaviour of the key functions called by this code? Note that the marks here are for the questions/hypotheses you raise, and not for the answers you find to the previous set of questions.
Part C: Reflection on the Exercise As a Whole
In this final exercise, you are asked to reflect on the exercise as a whole, and to draw some personalised lessons about your own approach to code reading.
Section C.1: New Domain and Technical Knowledge
The research into code reading suggests that, as well as extending our mental model of the program you are looking at, a code reading exercise will also add to your knowledge of the domain covered by the program and your knowledge of general programming techniques. List one example of how your knowledge of the e-mail domain has been extended through this exercise, plus one example of general technical/programming know-how that you have gained.
Section C.2: Writing Readable Code
The ease with which you can understand a new piece of code is affected in large measure by the choices made by the people who designed and implemented it (e.g. organisation of code, file/function/variable names). State 3 features of the Thunderbird code base that either helped or hindered you in attempting to read the code. For each one, describe a concrete action that you could take yourself when programming, to ensure that you do not make the same mistake.
Section C.3: The Top-Down Reading Approach
In this coursework, you have been asked to follow a set approach to code reading. For this final exercise, you are asked to reflect on this process, and to describe where you found it helpful and any ways in which you found it unhelpful. What was the most challenging part of the exercises, and what did you find the easiest? If you have your own preferred approach to code reading, you can describe it, saying why you feel it is more useful for you than the one proposed here. Or, you can describe ways in which you would modify the approach proposed, to improve it and to provide more support for the aspects you found challenging.

This coursework is structured into three parts: 1. Preparing to co...