Documenting the Design for your Programming Assignment

Author: Sharon Curtis

This article is aimed at undergraduates taking courses in programming. It is aimed at those who are a little more advanced than beginning programmers.

Programming assignments undertaken by students often have some marks allocated to documenting how the program is designed, and I often get questions from students about what kind of documentation is needed? What format should it be in?

Also, when I'm marking assignments, there is a great deal of variability in students' achievement when it comes to documenting their design. Some students have beautiful diagrams coupled with thorough explanation, whilst some other students hand in documentation that doesn't show their design very well at all. Some of this latter group, I have the sneaking suspicion, would be able to get more marks for their program design if they had more of an idea how they could present it.

The aim of this article is to discuss how to document the design to a program, with examples, for students attempting programming assignments. It covers the following:

• Following Instructions
• General Aims of your Documentation
• Data Structures and Datatypes
• Data Dictionary
• Organisation of your Program Code
• Design of your Program Code
  • Textual Explanation
  • Diagrams
  • Pseudocode
  • Stepwise Refinement
• Presentation and Formatting

Following Instructions

You will have been given some instructions for what you are to do in your programming assignment. So the first thing to note, is that you should read those instructions, note any information relevant to presenting the design of your program code, and then follow those instructions.

Also take a look at the marking scheme: how many marks are given for which design aspects of the assignment?

If you are unclear about any aspects of the instructions about the design of your program, then do contact the person in charge of the assignment and ask for clarification. It should say who authored the assignment on the handout; if not, contact the person in charge of the course you are taking. Lecturers and tutors would much rather that a student ask for clarification rather than turn in wrong or missing or misdirect work.

General Aims of your Documentation

The general aim of your design documentation is to explain how your program is designed: how it is organised, how it stores data, and what it does with the data.

Some of this information may well be in the comments of your code, if you have commented your code properly. However, typically for program assignments you get asked to provide additional written documentation too; this is because full explanations for program design do not fit into text-only program comments. You should still make sure your program is commented properly, however, as well as providing documentation.

Think of your documentation as explaining to another computer-literate person how your code works. You will want to explain your choice of variables and use of data structures, and also how your code works.

Data Structures and Datatypes

Programs all use data in some way; if they didn't then they would be pretty boring programs. So you will be using some kind of data structure(s) - and datatypes - in your programming, and you should explain what you are using. If the programming assignment heavily features data structures then this might be a big section of your documentation, otherwise it might be quite small if you are not using anything more interesting than an array.

Now if you did have to design a data structure and/or a datatype for a data structure as part of the assignment, then yes you do need to include some explanation as to what you chose and why. Explicitly state what data structure(s) you chose and explain how it stores the data, and state the datatype(s) you used for the data structure(s).

For example, in this sample design documentation for The ESP Game assignment, there is an explanation for the type of tree used and a statement of the Pascal datatypes used to represent such trees.

What can also be very helpful to explain your datatype is a diagram or two to illustrate how the data is stored. As well as explaining your design to the reader, this lets you demonstrating your understanding of the data structure(s). However, do explain your diagram in words too, don't just assume that the meaning of your beautiful diagram is as obvious to the reader as it is to you.

For example, in the sample design documentation for The ESP Game assignment, there is an diagram of the type of tree used to store the data, as well as a pointer diagram of the tree to show how this tree is stored inside the program.

Be smart about this though - if you were provided in the coursework handout with such a tree diagram, don't just repeat the same diagram! You're not going to get marks for demonstrating an ability to copy and paste(!). If however you use a completely different diagram showing an different example of the data structure with different data, then this can help demonstrate that you do understand how the data structure stores data, which can help you to get marks. For example, this tree diagram is completely different to the two tree diagrams given in the original handout.

Data Dictionary

A data dictionary can be a useful thing to include in your design documentation. A data dictionary is simply a list of what variables you have, together with what "roles" they each have in your program. Usually, a data dictionary will just list the global variables in a program, because the local variables in the procedures/functions of a program will get discussed when the design of those procedures/functions gets discussed.

An example of a data dictionary can be found here, in this example documentation for The ESP Game assignment.

Organisation of your Program Code

If you writing a small program for your programming assignment then your code may all be in one file, in which case you can ignore the following.

If however your code is in several files, and the organisation of code into files was something that you did, rather than whoever wrote the coursework handout, then it would be a good idea to explain which file does what - in other words, explain how your code is organised.

For example, in the sample answer for the design documentation of the ESP Game, there is the short description of what code is in which file:

Design of your Program Code

When explaining how your code actually works, one very useful tip is to go systematically through your program code, looking at the bits you coded yourself (as opposed to portions of code that you were provided with) and noting which bits need documentation.

Some small uninteresting portions of code may not need any documentation beyond what is already written in the code itself and the code comments. For example, a procedure like this is pretty much self-documenting, because you can tell at a glance what it is doing:

procedure introText;
begin
  writeln('Test Harness for a Linked Lists Program');
  writeln;writeln;
  writeln('Choose one of the following options.');
  writeln;writeln;
end; // introText

On the other hand, a procedure like the following could do with some further explanation; the pre- and post- conditions do give some explanation of what the code is supposed to achieve, but no indication of how it is achieving it:

function searchList(list: LinkedList; s: string): boolean;
// pre:  true
// post: searchList returns true if and only if s is
//       an item in the list
var tmp: PointerToListNode;
begin
  tmp := list.head;
  while (tmp<>nil) and (tmp^.data<>s) do
    tmp := tmp^.next;
  result := (tmp<>nil)
end; // searchList

Some ways that the design of your code can be explained include the following:

• textual explanation or description (in English)
• diagrams
• pseudocode
• stepwise refinement

Moreover, you can choose different ways of explaining your design for different parts of your code, depending on how best to explain it. Before we look at some examples, one word about the choice of how to explain your design:

Please do not include information just for the sake of putting something down, that does not tend to result in good documentation. For example, if the coursework handout says specifically to describe your code using pseudocode, then yes, go ahead and do so, otherwise you will lose marks. But if you are not specifically directed to use a particular method, then choose whatever helps to best describe the design of your program. You are aiming for a clear explanation of your design, and clarity matters more than some particular format.

Textual Explanation

You can explain the design of your code using English description. The aim is to be clear and explain to the reader how your code works, as if the reader is knowledgable about programming, but is not familiar with your particular piece of code.

For example, the above code could be described as follows:

Further examples of texual description of code can be found in the descriptions of the tree procedures in the sample design documentation for The ESP Game assignment.

Generally marks are not dependent on the spelling or grammar of your text (check the marking scheme of your assignment!), because it is a programming assignment that you are doing, not an English essay. However it is important to be able to communicate technical concepts clearly, so do take the opportunity to practise, and try and get the spelling and grammar correct. If your standard of writing is too low to convey clearly what you mean, then you may lose marks if the person marking your assignment can't understand what you wrote.

Diagrams

Diagrams are particularly useful for describing data structures (see above), but can also be used to describe code.

One common type of diagram to describe code is a flowchart. Flowcharts describe the "flow" of control of a process.

There are other types of diagrams, for example state transition diagrams can be useful if you have a lot of variables in your program representing state information (what state the program is it) and you want to show clearly how the state changes depending on what happens.

Another popular notation is UML, which is particular useful when programming using object-oriented languages. UML diagrams help to describe the relationships between one part of a program and another.

Depending on what information is conveyed by your diagram, if you choose to use one, you may find you need additional explanation to accompany your diagram.

Pseudocode

Pseudocode is a way of describing code that is a mix of text description and common code structures (such as those found in Pascal). The pseudocode should be formatted using proper indentation, because indentation is important for conveying the meaning of code. So you can think of pseudocode as text structured as code. The idea is that the use of text helps to provide a more human-readable explanation of what portions of code are doing.

For example, compare the above code to this pseudocode describing it:

searchList procedure:


  set temporary variable tmp to beginning of the list

  while (not at end of list yet)
        and (not found s at this node) do
    move tmp on to next element/node in list

  return result, will be true iff tmp<>nil

Sometimes I see students hand in documentation where they've tried to "reverse-engineer" pseudocode; instead of pseudocode, they have just repeated their actual code in the hope that this will pass for pseudocode. Do not do this! This will not get you marks for design, on the contrary, it will show that you don't know how to describe your design! Pseudocode is meant to be more explanatory than actual code, it is an outline of the design, not the implemented details. Pseudocode doesn't have obscure code statements in it, but instead has human-understandable description.

Note that as well as using pseudocode to describe the design of program details, pseudocode can also be used at higher levels of program description. It can be used to give an outline of what the program is meant to do. For example, here is an outline of the high-level program description for The ESP Game assignment.

Stepwise Refinement

Stepwise refinement is where you start with a high-level outline of your program design, and then gradually refine it to lower levels. Typically this method of showing the development of your design is done with pseudocode, and number labelling. The labels are used to indicate which bits of your program design you are refining further. It should be clear which portions of the implemented code correspond to which portions of the design.

An example can be seen here in the The ESP Game assignment, where the outline of the high-level program description for the game is then developed (refined) into more details of the game.

Again, don't just repeat your code in your documentation, putting number labels on it in the hope that it looks like pseudocode and stepwise refinement, because it won't. You have to start with a high-level description of your program, and start refining from there.

Presentation and Formatting

Refer to your code

In your design documentation, do refer to your code explicitly so that the reader can see which bit of the code you are talking about. For example, if you have a tree that stores some information in your program and you are discussing this tree, then explicitly give the name of the variable where this tree gets stored. If you are referring to some code to do some searching, then explicitly state which procedure or function it is that you are describing.

Acknowledge sources

Take care to acknowledge your sources. You need to be crystal clear about what you produced, and what you got (if anything) from elsewhere, because if you use someone else's work without acknowledgement, then that is plagiarism, which can result in severe penalties.

So, if you used code from the lecture notes, say so. Or if you adapted code from lecture notes or program used in a practical lab, then say that too. There is no problem in using other code sources as inspiration - it is how we all learn to be programmers, by seeing how other people did it and then using that knowledge to write our own code. Just make sure that credit is given where credit is due.

Include a code printout

If you are submitting a paper copy of your work, then be sure to include a copy of your code in your printed program documentation, so that the marker can easily write feedback comments on your code. Don't go to the trouble of copying and pasting it specially into a word-processed document - it is more effort for you and can often make it more difficult to read.

Instead, simply print it off from a text editor or programming development environment. Ideally, if you can, print it off with line numbers, that way it makes it very easy to refer to specific sections of code in the rest of your documentation.

Formatting

Don't spend too much time on prettifying your work. If you want to practise your word-processing skills, fine, but be aware that your beautiful title page and the drop-shadows and gradient-shading you did on the boxes in your diagram isn't going to get you extra marks because it's a programming assignment, not a document-beautifying assignment.

What is important, besides the contents of your documentation, is that your work is presently clearly and legibly, because we can't assess the content of your work unless we can read and understand what you are saying.

For example, here's a quick time-saver - if you can hand-draw legible diagrams (e.g. for binary trees or linked lists) then leave a space in your word-processed document for including a hand-drawn diagram - it is very easy to draw trees or pointer diagrams legibly, and it is much quicker than laboriously drawing such a diagram using a word processor.

Repeating information

When actually writing the documentation, just document the portions of code that you actually wrote, not the code that you were supplied with by the lecturer (if any). Every time I mark coursework, I see several students repeating in the documentation information that they got from the coursework instructions. Ok, there's no harm in including that information for completeness, if you feel better in doing that, just don't expect to get marks for repeating the instructions, that's all!

The design of unimplemented code

You may be able to get marks for the design of parts of the program even if you didn't manage to fully implement it or get it to compile or debug it. So by all means include design information for unimplemented / unfinished code, but please indicate clearly that you didn't finish / implement that bit, otherwise you may confuse the person marking your documentation.

Stapling

If you are submitting a paper copy of your documentation, then make sure it is securely fastened. Some tutors may prefer it stapled, others may prefer looseleaf inside a plastic wallet; just follow the written instructions.

Make sure that your documentation has page numbers on it, so that if the pages are detached then it is still clear which page is which.