Tag Archives: students

Un-learning your coursework: Commenting

In an effort to not lose points on their grade, many students will end up writing code like this:

#include <stdio.h>   // For input and output
#include <string.h>  // For string-related functions

// Main method
int main(int argc, char* argv[])
{
    int numChars = 0; // create integer variable numCharacters and set it to 0
    for (int i = 0; i < argc; ++i) // loop once for each argument
    {
        numChars += strlen(argv[i]); // add the length of string argv[i] to numChars
    }
    printf("Number of characters in arguments: %d\n", numChars); // Output the calculated number of characters
    return 0; // no errors while running
} // end main

The excess of comments clutters the code and makes it less readable, the exact opposite of your goal. Even worse, some graders will take points off if you don’t comment this heavily. Ugh.

For your coursework, just go along with whatever the instructor asks for; commenting style is not worth sacrificing your grades over. In the meantime, start un-learning some bad habits by considering the advice below.

Don’t point out the obvious.

Let your code speak for itself. Any programmer who looks at your code will know that “++i;” means that i is being incremented; you don’t need to repeat that information. The same goes for common programming idioms; for example, it’s pretty easy to recognize “for (i = 0; i < value; ++i)” as looping through something value times.

Save comments for when you’re doing something subtle or unintuitive. Of course, if you end up in that situation, remember this next guideline:

Bad code requires many comments. Good code needs few.

If you’re anything like me, your first impulse when you realize your code is hard to follow is to write a comment explaining it. However, “just comment it” shouldn’t be the first solution. If possible, try to re-write the code so it’s clearer.

Comment bug fixes.

Depending on how you fix a bug, it might be worth putting a comment there explaining the bug you just fixed. It prevents the problem of someone coming along later (possibly even yourself!) and saying, “This is over-complicated. I’ll just re-write it to be simpler…” and re-introducing a bug you already fixed. That being said, if you’re using unit tests, you’re probably safe if you just write a regression test for that bug and call it a day.

// Good example: explains a possibly unintuitive piece of code
void updatePlayer(Player& player)
{
   ...
   if (player.x > CAMERA_BOUNDS)
      doSomething();   // BUGFIX: Prevents the edge case where [...]
   ...
}

// Bad example: points out the obvious
void someFunction()
{
   int x = 0;
   while(x < 10)
   {
      ...
      ++x; // BUGFIX: loop didn't end
   }
}

Comment function headers.

You can probably guess what this function does if you find it in a header file:

float max(float x, float y);

However, you don’t want to code based on “this function probably does what I want it to.” You’ll probably go through the code and double-check what it does – no big deal, the function is only two lines anyway, right? And then so will everyone else who uses this function. Every. Single. Time.

You don’t necessarily need a super-verbose JavaDoc-style comment at the top of every function, but you should at least write a quick comment saying what the function does:

// Returns the greater of two floats
float max(float x, float y);

Furthermore, if someone else forgot to add in that comment, write it yourself after you figure out the function and save everyone some time. Make sure you’re correct, though! Incorrect comments are worse than no comments in most cases.

Stick to established commenting styles

Even if there’s no official, formal commenting policy for a project, please keep your new code consistent with the old. Remember just above where I said “You don’t necessarily need a super-verbose JavaDoc-style comment…”? That doesn’t apply if every other function in your project has one. Consistency trumps personal preference here.

Follow these guidelines judiciously.

No rules are set in stone. Let’s say you’re using a super-fast but super-complex algorithm because you’ve optimized that part of your code heavily. Of course it’s going to require a lot of comments. Just make sure to keep that complexity encapsulated behind a nice interface.

With that, I’ll leave you with how I would personally write the program at the top of this post:

// Arglength - Prints the total number of characters passed in as arguments, including the program name
// Author: Zachary Hoefler

#include <stdio.h>
#include <string.h>

// Entry point
int main(int argc, char* argv[])
{
    int numChars = 0;
    for (int i = 0; i < argc; ++i)
    {
        numChars += strlen(argv[i]);
    }
    printf("Number of characters in arguments: %d\n", numChars);

    return 0;
}

Troubleshooting your job search

Having trouble finding a job (or co-op/internship)? Here’s some advice:

Frustrated man

First, try to relax. (Click image for source)

If you’re submitting a lot of applications and not hearing back…

  • Refine and polish your resume. The one goal of your resume is to get you to an interview.
  • If your skills are too weak to have a solid resume, spend time working to improve them. Whether that means working on side projects, reading books, or anything else you can think of, don’t just sit around and expect things to improve.
  • How are your cover letters? Do you have others review them with the same scrutiny as your resume? If not, why not?
  • Are you persistent with your applications, or do you just send an email and forget about it unless you get a reply?
  • Are you being realistic about the companies you apply to? Finding a co-op is very much like a college search: by all means, apply for a “reach” (e.g. Blizzard, LucasArts, EA, etc.), but don’t count on it. Even if you’re a rockstar student, getting a highly-competed-for internship at a AAA studio is a crapshoot.
  • How many applications are you submitting? If you’ve only applied to 5-10 places, you’re not trying very hard yet.

If you’re getting to the interviews and not getting a position…

  • Have you practiced your interviewing skills? Do mock interviews, read books (e.g. Cracking the Coding Interview for programmers), and get all the advice you can.
  • What sorts of questions give you trouble? Have you worked on improving your abilities there?
  • Do you appropriately research the company beforehand, or jump in blind?
  • Are you enthusiastic, or do you not sound interested? Are you modest, or do you come off as cocky?
  • As a student: do you show potential? Nobody will expect you to be a programming guru while in school; however, interviewers are looking for someone who’s able to learn and improve.
  • Do you ask questions at the end of the interview? A pretty easy (and useful!) one is, “why did you decide to work at [company]?” Remember, it’s not just a chance for them to get to know you, it’s a chance for you to see if you want to work there.

After the interview, when you’ve been rejected…

  • Follow up briefly and thank them for their time. Ask when a good time to apply again would be (generally a year). Even if you didn’t get the job now, that doesn’t mean you can’t get a job there – it just didn’t pan out this time.
  • If you’re truly at a loss as to why nobody’s accepting you, you can try asking for feedback. Don’t get your hopes up, though; HR departments are incredibly busy at most companies. Don’t take it personally if they don’t get back to you. If you’re lucky, though, you’ll get a reply that might help you in the future!
  • Reflect on why you think you might not have gotten the position. Try and shore up any weaknesses that come to mind.
  • Keep at it! You’ll find work eventually, but you have to work for it!