Comments, names, functions

Andrew Bennett <andrew.bennett@unsw.edu.au>, COMP1511 19T1 Course Forum

Student:

I might have heaps of scattering lines of codes which will be defs put in comments. They're mainly used for debugging or possible improvement, so do I need to remove them for submission purpose or leave them there for the markers' testing? Or it just doesn't matter?

Could you give me hypothetical example of what you mean? Don't actually paste something from your assignment code here, but make up some comments that are along the lines of what you would write for the assignment.

Why, not what

Some general advice for comments -- your comments should focus on explaining why your code is doing something, rather than on what it's doing.

If you need a comment to explain what a certain piece of your code is doing, then you should probably rewrite that code so that it's easy to understand without needing comments.

(It's also often a sign that you should move that piece of code into a well-named function, and just call that function instead -- I'll write up an example of what I mean in one of the "followup discussions" below).

Function comments

You should also have a comment at the start of each of your functions, explaining what the function is for, and how it works if necessary, but without restating the obvious.

As in, don't have a comment saying "this function has a loop which loops through the array and counts how many threes there are in the array" -- someone can (or should be able to, at least) tell from looking at the code in the function that it's a loop that looks through an array and counts how many threes there are in it.

It would be better to explain what the function is for -- why is it useful to count how many threes there are? What's the purpose behind it?

Comments in general should add to the readability and understanding of your code, rather than detracting from it.

So, having really long messy comments that are just some rambling that you wrote at 5am is unlikely to be a good idea.

But it's definitely okay (and maybe even useful) to have comments about e.g. things that you tried that didn't work, or other things that you were going to do but weren't able to -- maybe even ideas you had for what you wanted to do, but which you weren't able to get working / couldn't work out how to do them.

I guess a way to sum that up is to think of your final version of your assignment code as if it's an artwork or a book that you were publishing.

You want it to be in a finished state (i.e. not just a bunch of long rambling), so that overall somebody can read your code from start to end and understand what you're doing and why you're doing it.

But, it would be really weird to publish a book where one of the chapters in the middle is just a bunch of drafts of half-written paragraphs, but it's totally fine for the book itself to discuss concepts that you got partway through.... if that makes sense?

But, like I said at the start, if you can give me a hypothetical example of what you mean, I can give more specific/useful feedback as to how suitable/useful that sort of comment would be.

Student:

Some of my comments for a function are like these:

// This functions checks if any two numbers are co-composite or co-primed
// If a,b are co-primed -> return 0. Otherwise, return 1.
// Note: printf in this function is used for debugging purpose
int cocompostie_check(int a, int b){
	...
	//printf("....");   <- for debugging: print variable values out to check
	...
} 

So I know I didn't fall of the track of just saying "this function has a loop which loops through the array and counts how many threes there are in the array" like you mentioned but still not sure if the language is suitable though.

In terms of your comments:

The first two lines are great, it describes what the function does (check whether it's co-composite / co-prime), and what it returns (0 if coprime, 1 if cocomposite).

A brief sidenote there -- rather than having a function called cocompostie_check which returns effectively "yes" if it's cocomposite and "no" if it's not, why not instead call it is_cocomposite?

That way, when you're reading the code that calls it, it will look something like:

if (is_cocomposite(num1, num2)) {
    // ....
}

You can very clearly read this as "this function checks whether it's cocomposite", as in, it answers the question of "are these two numbers cocomposite?".

If you compare that to cocomposite_check

if (cocomposite_check(num1, num2)) {
    // ....
}

The name cocomposite_check isn't bad, you wouldn't lose marks for that name, but your code would be clearer with a name that's asking a question.

(When marking, this is the sort of thing that I'd leave a comment on, saying that it would be better to call it is_cocomposite, but definitely wouldn't deduct any marks for)

In terms of the debugging printfs... there's no clear "right" or "wrong" answer here.

I think it would be better to remove the printfs, on the basis that is_cocomposite should be an easy enough function to get right, so once you've finished writing the function (and testing it on a range of values), you shouldn't need to use the debug prints again, if that makes sense?

Here's an example of some "real" code I wrote (a ~1000 line solution to one of the very hard hopefully-upcoming challenge exercises), modified so that it doesn't give anything away:

void do_something(blah blah blah parameters) {

    // [comment added for this post, not in original code:
    // don't worry about what a "FILE *" is, that's irrelevant here]
    FILE *input = get_input(blah blah blah);

    int some_array[MAX_SIZE] = {0};

    // [comment added for this post, not in original code:
    // again don't worry about what EOF means, also irrelevant]
    while (get_next_thing(input, some_array) != EOF) {
        do_some_complicated_thing(blah blah blah);
    }

    // print_some_array(blah blah);
}

This function handed the initial processing of the input, where it had to go through a large input file and do some initial analysis/computation on that input file -- the end result was then the processed input that my program used to solve the problem.

Being able to print out and read the processed input was very helpful for when I was trying to get the subsequent functions to work, so when something went wrong with one of the subsequent functions that calculated the answer, I'd uncomment that printf so that I could see what the processed input looked like.

It would also be helpful for somebody who was reading the code who wanted to see how it worked to be able to see what the processed input would look like, so if they downloaded the code and ran it themselves with a range of input files, they could uncomment that printf themselves to see what the processed input looks like for whatever input file they gave it.

I think this again comes down to the parallel of wanting to publish a book that you've written (which you've finished writing and is ready to be published) -- you wouldn't leave in your little notes-to-self that you'd scribbled on your draft manuscript when you published it, but it would be entirely reasonable to have an optional chapter at the end that explains something in detail for the people who want to read more about it (but which doesn't interrupt the reading flow for anyone who doesn't want to skip to that section at the end to read it).

Hopefully that all makes sense (and hopefully it is also helpful) :)