COMP151, Lab 1B

TA: Marine CARPUAT
OFFICE: Human Language Technology Center, room 2580 (lifts 27/28 and 29/30)
marine@cs.ust.hk · http://www.cs.ust.hk/~marine/
OFFICE HOURS: Monday, 12:00--2:00pm.

Course web page

Main Lab web page

Announcements

You can check your grades here.

Remember to sign the attendance sheet: attendance counts for 3pts in your lab grade.

Here's a list of common mistakes that some of you made in the previous assignments. Learn from them!

Lab02: Separate Compilation and Makefiles

Your tasks for this lab are on the Lab 02 main page.

Make sure you always document your code properly... Not only for this lab, but for all labs, all assignments, and every piece of code you write.

Why document your code?

Comment your code so that someone who has no idea what the code does can understand it. And keep in mind that, one day, that someone will be you!

What are useful comments?

Compare the 2 comments below:

Comment A:
perimeter = a + b + c; //compute perimeter by summing the lengths of the sides.
Comment B:
perimeter = a + b + c; //compute the sum of a, b and c.

Comment B is useless because it only repeats the code without adding new information. In contrast, comment A provides useful information by explaining the purpose of this particular line of code.

The Javadoc style guide contains a good example of useful vs. useless API description, and other comment writing style tips.

Writing documentation with Doxygen

Doxygen is a documentation system for C++, C, and other programming languages, that automatically generates documentation in both html and LaTeX format, for a set of source files that are documented in a specific format.

Running Doxygen will not only give you a nicely formatted documentation, it will also help keep your documentation complete and consistent.

4 simple steps

Document *ALL* your classes and functions using Doxygen style comments ( see examples below)
Generate a doxygen config file by typing
doxygen -g doxygen.config
in the directory where your source files are.
Use pico to edit the doxygen.config file. For instance, you can change the project name (e.g. call it "lab02"), the output directory (e.g. call it "doc"), and other parameters as you see fit.
run doxygen doxygen.config

DONE! you can now open doc/html/index.html to browse the html documentation for your code.

For a more detailed introduction, check out the Doxygen manual

Writing comments for Doxygen

Here is an example of the use of Doxygen comment blocks. A Doxygen documentation block is a C or C++ style comment block with some additional markings, so that Doxygen knows it is a piece of documentation that needs to end up in the generated documentation.

For more details, consult the Doxygen manual section on Documenting the code.

Some Doxygen tips

If you want ALL your comments to appear in the generated Doxygen documentation, including comments in the main function, comments for private members, etc., you should set the following parameters in the config file:

EXTRACT_ALL = YES EXTRACT_PRIVATE = YES EXTRACT_STATIC = YES EXTRACT_LOCAL_CLASSES = YES EXTRACT_LOCAL_METHODS = YES

Lab04: Linked-List Implementation

The lab main page is here.

At the top of the files that you submit, please remember to write down your name and student ID, and also the names of your collaborators. Thanks!

Use Doxygen!

Starting today, your code for labs and assignments has to be documented using Doxygen!

You can get the Doxygen documented code for lab04 here:

You should unzip the files as follows:
tar -xzvf simple.tgz
tar -xzvf circular.tgz

Remember the plagiarism and collaboration policies!

ALL materials submitted for grading must be your own work.

You are encouraged to collaborate with your classmates. However, you must write up solutions on your own. You must also acknowledge your collaborators in the write-up for each problem, whether or not they are classmates. Other cases will be dealt with as plagiarism.