Undergraduate Capstone Open Source Projects

Importance of Code Comments

Posted by plorimer on 2009/10/15

The further I go in my computing education, the more entertaining I find it to look back on previous assignments and projects that I have worked on. It’s entertaining because the code that I wrote as a first year, is in my opinion terrible. It’s not only the fact that my code was terribly inefficient, it’s the fact that I have no clue what I was doing at all. I say to myself wow! that was a really stupid way of doing that, why would I do that? The problem is I will never know, I never really made useful comments.

I think that code commenting is something that is really important, at least for me. This article on why code commenting is so important, is pretty interesting.  The article mentions code that is self documenting, that there is no such thing. I think that code can be self documenting, but I don’t think that alone is enough.

The reason I find this interesting is because when I was in my earlier years as a compsci student, I thought that I would just not comment in the workplace. Thus, giving myself a niche and great job security. I know this sounds stupid, but thats the way I thought. I have since realised that would be insanity. It has nothing to do with the fact that other people would not be able to read my code. It has everything to do with the fact that after I don’t look at a piece of code for 24 hours I have no clue what I was doing. Call me forgetful, but I know that there are many others out there like that.

After working some time on the IDE4EDU project, I realise the importance of proper documentation. If everyone just assumed that what they did was common sense, large software projects like Eclipse would be in shambles.

Now considering commenting was never really enforced until mid way into my second year. I’m of the opinion code comments should be worth close to the same amount as functional code from year one. That’s just my opinion.

2 Responses to “Importance of Code Comments”

  1. John Peters said

    Great article; thanks for the post.

    Commenting lines of code is important, certainly. But I find that what I’m desperately needing when I’m having trouble understanding code is documentation the next level up. Unless the code within a function is hackish or unintuitive, I’m able to understand what the function does to the inputs and what it returns. But I don’t understand why the function (or class, or whatever) was written the way it was. I can use grep or an IDE to discover what other parts of an application depend on the function/file you’re looking at, but that doesn’t necessarily tell me what place the function/file has in the application. For me, a ten line block comment describing an entire file is worth more that twenty single line comments scattered throughout the code.

  2. plorimer said

    I agree completely, I don’t consider one line commenting throughout methods to be commenting. In the article it says those comments are useless. Comments that are important are the large blocks, telling how and why a method was implemented the way it was. And how it is used.

Leave a Reply

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 )

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s

%d bloggers like this: