Reports

I've come to the startling conclusion that your average engineering student can't follow simple instructions, and can't write even a basic report. Ignoring the fact that most of them cannot seem to master the mechanics of the spelling or grammar check buttons (put mouse over button, click, release), the reports that I've been getting are overwhelmingly terrible.

The previous lab assignment was to emulate a pulse width modulation (PWM) controller using an embedded computer and a simple program, written in C. PWM is, if I may be allowed to terribly oversimplify, the process of sending out pulses of different widths onto a wire. The width of the pulse represents it's value, so a pulse of 5 milliseconds could be considered to have a value of "5". PWM is no longer a common technique, but it can be useful for controlling certain servo motors. The task was broken into four parts:

1. Determine the absolute fastest rate at which a program written in C can cycle the output port on and off. In other words, what is the smallest that our pulse widths can be.
   
2. Depending on the findings in part (1) above, determine whether a specific set of pulse-width specifications can be met by your system.
3. Write a program that outputs pulses of specific widths. Pulse widths are specified as fractions of a constant cycle time. Pulses of 8 different widths are required.
4. Measure the actual width of the pulses using a logic analyzer, and calculate the percent error between your system output, and the specifications.

One student wrote the following code snippet (I've added a few simplifications for readability) for part (1):

while(!kbhit()) {
outportb(PORT_A, 0x01);        //turn bit0 on
printf("PORT A Value is: %X\n", (int) inportb(PORT_A));
outportb(PORT_A, 0x00);     //turn bit0 off
printf("PORT A Value is %X\n", (int) inportb(PORT_A));
}

The student, after running the above code, found that the pulse cycle time was several orders of magnitude higher then the maximum specification value. Can you see why? These students are assembly language programmers, and they're used to instructions executing, more or less, in a single "instruction time". For that reason, many of them don't have the conceptual understanding that the printf command is not some small atomic command, and that it doesn't execute in a reasonable amount of time. The printf function has a number of tasks to perform:

1. Output characters from the format string to stdout, checking whether every character is a "%" character.
2. If the character is a "%", determine what type of argument is needed.
3. Pop an element off the stack, convert it into a string depending on what type it is.
4. Print that string to stdout as well.
5. Count and return the total number of characters printed (although this return value is rarely used)

printf likely calls some kind of lower-level i/o routine, such as putc or puts, which in turn needs to interface with the display driver. Cutting the printf statements out of the code snippet above decreases the output cycle time from slightly above 15 milliseconds to less then 15 microseconds, which is well within the required range for the assignment.

I'm not a stickler for formatting or details. In my lab, I require students to only have three sections in their reports:

1. Introduction: A short description, of one or two sentences, of what the assignment was. What problem are the students trying to solve? Being succinct and accurate shows that the student understands the problem and is able to rephrase that problem in their own words.
   
2. Procedure: A description of the program that the student wrote, including explanation of algorithm, structure of code, etc. This is one of the most important parts of the lab report, because it gives the student an opportunity to explain that they know what's going on, even if their code does not work. Describing what you are trying to do demonstrates that you understand the necessary concepts, and that you understand how to solve the problem, even if your code did not "work".
3. Results: Did your program work? If so, how well? If not, why? Explain what the results of the lab were, describe how it could be made better. This shows that the student's code worked, how well it works, and whether the students are able to learn from their mistakes.

Even with these very relaxed requirements, I still find myself needing to write "Explain more!" in big red letters. I don't ask for much, but I need to see something. One student wrote, as his entire procedure section, the following paragraph:

First write program that using loop to turn on and off the port continuously. Then using logic analyzer to see what pulse width and cycle time values are. To get pulse width = 0.2 cycle time. Puts another loop in program to modify the time of pulse on and off.

It puts the lotion on it's skin.... Now, I don't grade based on spelling or grammar (the engineering department says specifically that I am not supposed to), but this is basically illegible. Besides that, it doesn't explain what his code does. When I read through the code, I see very quickly that his code doesn't actually do anything. It doesn't output any data to any I/O port. It doesn't have any loops to modify pulse times. In short, he described a program that he didn't write for his report, and handed in a program that he didn't describe.