XML CO538 Anonymous Questions and Answers Keyword Index

This page provides a keyword index to questions and answers. Clicking on a keyword will take you to a page containing all questions and answers for that keyword, grouped by year.

To submit a question, use the anonymous questions page. You may find the keyword index and/or top-level index useful for locating past questions and answers.

Keyword reference for comments

Question 52 (2012):

Submission reference: IN2315

How much commenting should we put in our code for Life on Mars?

Answer 52:

See Question 30 (2001) for the kinds of comment that should not be made!

Otherwise, you should summarise the purpose of each program entity (e.g. PROC or PROTOCOL) in comments just above its header. Ideally, this should conform to the syntax for occamDoc documentation used in, for example, your q4.occ and q7.occ starter codes and PROC draw.hit.line in the mars-sim.occ file. However, free-format comments will be fine.

In the body of a PROC, 'clever' code must be explained – anything whose purpose would not be obvious to a reader familiar, in this context, with occam-pi. For example, if there is special code to eliminate a danger of deadlock but not otherwise contributing to the purpose documented above the header, you must explain why it's there and how it does its job. It's essential to make your code understandable to readers. A base reason would be that they might be marking it! But one of those readers might be you in a few weeks time and, just because you understood it once, this does not mean you will understand it in the future. Obscure code is, in practice, worthless ... regardless of whether it works or is efficient. Obscure code cannot be maintained. Code that cannot be maintained will be thrown away.

Diagrams are an important part of the documentation of occam-pi systems. Remember to submit a process network diagram (or diagrams) if you have used concurrency in your robot.control logic. This is needed even for networks that are temporary (e.g. for the duration of a turn, move, find or deploy), but not if the concurrency is very short-lived (e.g. a parallel input/output). Diagrams for temporary networks should be enclosed in a box labelled by the PROC that sets it up (with all its external channels) and some text (or number scheme) that indicates when it is set up and for how long it lasts.

Keywords: mars , comments , diagrams

Question 30 (2001):

Do we have to comment our code as it is fairly self explanatory and just makes the code look more unreadable?

Answer 30:

Comments should be used to clarify code. If they make it less readable, they are bad comments! Comments that confuse or add no information will be penalised - e.g.

  SEQ
    in ? x         -- input from channel 'in' into 'x'
    x := x + 1     -- increment 'x' by one

For further general comments about comments, see the answer to Question 12 (2001).

Keywords: comments

Referrers: Question 52 (2012)

Question 12 (2001):

Do we have to comment our code - or will the diagrams be enough to explain things?

Answer 12:

You need to draw diagrams for any changes needed in the diagrams already given in your q4.occ starter file. This will be for the network diagram of your top-level q4.occ process. You also need to draw - separately - diagrams for your revised numbers, integrate and pairs processes. Please note the standards for diagrams given in the second note to the answer to Question 4 (2001). As for commenting, please refer back to the answer to Question 6 (2001).

Keywords: comments

Referrers: Question 30 (2001)

Question 6 (2001):

Please define "adequately commented". Surely in a program this simple (q2) there is no need for comments - as you can see what the program does by reading the code?

Also, is this a suitable network diagram?

     |------------|   |---------------|
  -->| Intergrate |-->| Differentiate |-->
     |------------|   |---------------|

Answer 6:

The third Note in the answer to Question 4 (2001) says: "adequately (but not over-) commented". This is a general note about comments that applies to any code you write. For this question, however, no comments are probably needed - unless you have designed something a bit obscure for your differentiate! The definition of "a bit obscure" is anything that is not immediately obvious to whoever is marking your script. Please note the other remarks in that third Note - which are always relevant to your answers, including this one.

Your diagram above is a network diagram ... but it is not suitable as an answer to this q2 assignment. The second Note in the answer to Question 4 (2001) says that you must include network diagrams of "your differentiate and q2 processes". The above does neither of those. [Also, please spell "Intergrate" correctly.]

Keywords: comments

Referrers: Question 12 (2001)

Question 4 (2001):

When is our first assignment (q2.occ) due?

Answer 4:

A hard-copy listing of your source code should be handed in to the CAS office by close of service (around 4pm) on Thursday, 8th. November, 2001. Cover sheets will be made available next week.

Note: remember that your differentiate process should be implemented in the same style as the implementation of integrate -- i.e. as a network of simple components of the level of those in the demo_cycles.occ library (see slides 5-3 and 5-8). This requirement is made in the comments in your q2.occ starter file. A solution for differentiate in the form of a single serial process will get a maximum of 6 out of 10. [See also the Hint: given in those comments.]

Note: you must include network diagrams of your differentiate and q2 processes (the latter contains your test rig). These can be hand-drawn neatly on your hard-copy listing or machine-drawn on other paper and stapled to your listing. The diagrams should be annotated with process/channel names that correspond to those used in your code. Channels should be arrowed to show the direction of data-flow. Also, think carefully about the icon you choose to represent the minus component. Unlike plus, minus is not symmetric over its input channels and your icon must reflect this. When looking at its use in a network diagram, we must be able to tell which channel numbers are being subtracted from which.

Note: your source code must be adequately (but not over-) commented, should use meaningful variable names and be well laid out. Of course, you have no choice in indentation layout (;-), but spacing within lines and between them (e.g. between PROC declarations) helps readability (and marking!).

Note: comments in occam source code are introduced by two dashes, --, and include everything following this symbol to the end of the line. [This works like // in Java.]

Keywords: q2 , diagrams , comments

Referrers: Question 6 (2001) , Question 6 (2001) , Question 12 (2001)