Commenting Code

You know, whenever I’ve TA’d a first year class, I’ve always stressed how important it is to comment your code. That commenting provides details about what you’re trying to do and how you’re doing it. In fact, one semester, when I was posting solutions to assignments and labs, I purposely over commented the code. I wanted it to be very clear and easy for students to be able to follow what I did and why.

However, as much I’ve been great at stressing it and even using it myself to teach others, I’m terrible at using it myself. I’ll start off with lofty goals that quickly get pushed to the side. I’ve never managed to make commenting a natural part of coding for me. Which, when you end up coding a giant project (which mine is) ends up being a bit of a nightmare and often ends up making stuff a lot harder than it should be.

And so, on my giant and ever growing list of tasks, I have “go through and comment” as one of them. Of course, it’s pretty much one I’ll never be able to cross off. Even if I do take the time (and I will, I swear) to go through what I have, unless I manage to improve and forever more comment as I code, I’ll end up needing to do another pass (and another and another…). And, based on past promises on changing my ways, it’s unlikely that this is the time it’s going to work.

I think the idea of commenting code (which really boils down to making notes on something) can also be transferred to how you work on and keep track of other work. I know, that idea sounds kind of odd. Where else are the idea of comments all that useful? Well, here are some other places where I have used them in the past and think it’s worth using them in the future:

  • When writing papers using Latex. You can keep track of sections you need to remove, or remind yourself why you’re including something. As you’re making progress, you can leave yourself notes about what’s missing and what you still need to do or double check.
  • In your bibtex files. You can leave notes about the papers you’ve read such as where you’ve stored it or something interesting you want to remember about it.
  • On your to-do lists. Many tasks can be described in a few words such as “Step 3 ideas.” But, I’ll often want to keep notes on some of the stuff I’ve already thought of or links I want to re-check out.
  • On papers you’ve read. Right now, I’m using a text file to keep track of stuff, but the same idea could be used by commenting directly on pdfs and storing your thoughts that way.

And, I have to note, that I’m better at commenting/making notes on everything but code. With so much information flying around now-a-days, and the number of things we’re required to keep track of, I think remembering to take notes is becoming increasingly important. I find there’s just too many things to reliably be able to keep track of everything without notes.

Do you find you’re commenting or keeping notes all over the place? If not, what’s your secret/method to keep track of what’s going on?

Advertisements

2 thoughts on “Commenting Code

  1. I think a better approach is to let your code comment itself with explanatory method and variable names. Don’t get me wrong there are times where a little explanation is GOING to be necessary but if you are doing your job well then there should be little commenting necessary other than maybe explaining WHY you did something some way.
    Here is a good read on the subject http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

    • While I agree that method and variable names can go a long way, I don’t think they’re always enough. By commenting code, I don’t mean that I need to be writing paragraphs about what each method is going to do. But to instead add in those short lines to clarify the goal of what is being done. Just enough to help out and speed up the time it takes to remember what is going on and why.

Join the discussion

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s