Strides Interactive

Comment your codes or not?Filed Under: Weekly Tuesday Dose of goodness

Hi all,

I know I’ve spoken about code comments before. However, recently I came across a post that encourages people not to comment at all.

His argument states that having a good naming convention is entirely sufficient to tell people what you intend to do.

I was quite aghast and shocked to witness such technical immaturity!

To find out more… read on.

Introduction

First of all, I must say that I have little tolerance to people championing for a certain technical capability or methodology without a careful thought process. This is especially so when this methodology has been proven to be immature in a robust software development industry.

Which therefore explains why I’m a little pissed off at people who make several stupid implicit assumptions which I’ll explain later on.

About myself

Before I start ranting about the allegations, let me just share with you a little of myself. I’ve been a developer, full-time for 2 years, part-time on my own account for almost 11 years! I’ve managed my own project alone with a source code base size of 160,000 lines of codes.

Many a times, I find myself doing stupid things not due to poor design. But rather, due to poor documentations. Codes that fail to explain themselves in terms of design rationale has caused me quite a big headache in the past.

But now, all that has changed. I’m responsible to myself as well as my team who may have read my codes. I’ll do my best to make sure that they can easily understand what I’m doing at a glance.

Codes are now properly documented in areas with ambiguity and all public methods are documented with code comments for a very simple reason.

In Visual Studio, intellisense can easily seek out comments above definitions. Therefore, by placing a well-written set of comments to describe the public method, it helps my team to understand the behavior and contract of this method before passing in their data. Here’s an example below:

//---------------------------------------------------------------------------------
// Pick and stores the objects into a given linked list based on an AABB
//
// Parm :
//      cLinkedList< cCollisionUnitInstancePtr >& - A reference to a valid linked
//                                                  list that stores a collision
//                                                  unit instance pointer.
//                                                  Preferrably empty. (OUT)
//      cAxisAlignedBox& - A reference to a valid AABB used for picking
//                               objects. (IN)
//---------------------------------------------------------------------------------

How can these kind of code documentations help the team? Well, Visual Studio prints out these documentations in an entire mini-window, allowing my team mates to read them and know what to pass into it. The (IN) and (OUT) keywords also highlight the data flow of the method.

Thus, without the need to go into my codes, they’ll be able to use it with adequate knowledge of what it does.

So enough of this, let’s get to the case in point.

Case in point

1) Code comments make your codes hard to read
2) A well-written piece of code needs no documentation
3) Comments are written only for codes with design flaws

My point of view

1) Code comments make your codes hard to read

Only coding grunts will say such things because all they do is to code. Whether they do it correct or not is secondary. But they want to have a kick of playing god.

Just write something, stupid or not, correct not, I don’t give a damned. I throw it to the compiler, it says ok and I’m done. I keep my fingers crossed hoping that my slingshot effort can pay off. - What a load of bullshit!

If there’s even a need to read the codes, then I must say, the method documentation wasn’t properly done.

Why must you even read the codes?? A good developer knows what are his tools and how he can intelligently splice them up together to form a component. Knowing this tools doesn’t mean knowing how it’s being made.

I don’t need to know how the hammer head is cast in order use it! If I need to know, then the hammer must have been broken way too easily for me to question!

Guess what? These people don’t even bother to read the code documentations properly to understand what they’re supposed to do. Therefore, they rewrite the whole set of codes, sometimes even shamelessly do a wholesale copy and paste from the original source codes. Then they themselves grill at it until they understand, condemn its original author for making them go through the shit they did and then proclaim that they’re the original owner of the same piece of source code when it was original written by others.

If you really need to read the code documentations for some reason, then do it! Without code documentations, it’ll be much harder to understand why the original author did the way he/she did it.

Grilling through the source codes is one of the stupidest things a developer could do. If he/she chooses to do it without reading the code documentations first, then this developer should be re-evaluated and be fired if necessary.

2) A well-written piece of code needs no documentation

Again, this line is a said by someone who has very limited experience in programming or has done very simple or straightforward tasks in the past.

In short, this is a statement that can only come from a mediocre programmer.

Yes, I’m harsh but if you ask yourself, since when codes are easily understood? How many times do we have to grill through source codes in order to understand how they work? Almost every time!

And Why? Just because someone thinks the way he/she did as described in the point above.

Programming is based on a language yes? But it’s also based on a perspective. This perspective comes from a thought process that revolves (hopefully) around the technical specifications.

The very same technical specification can be achieved by one or more persons all producing a very different set of codes.

Thus, the notion of well-written can be disputed since it’s subjective. A well-written piece of code should conform minimally to the requirements. There’re many more that help self and others to understand but this is hugely ignored due to time constraints.

If there isn’t a problem, then it’s ok. But when there’s a problem, I can almost guarantee you that desperation will set in. Why? Because of this stupid assumption! What are you left with when the world comes apart? A piece of a code with an assumption that it’s well-written and can be read by anyone AND can be understood by anyone without any difficulty.

That’s quite a big boast if you ask me. Complete bullshit!

On the other hand, a properly commented piece of source code, ie, with steps indicating its sub-role in the code will help the developer identify issues very quickly. Here’s an example:

    //Step 1 : Check the list, see if it exists or not
    if(!this->boundsList.find(parmListName))
        return false;

    //Step 2 : Check the iterator to see if the iterator exists or not
    if(!this->currentIterator || this->currentIterator.getSize() == 0)
        return false;          

    //Step 3 : Check if the iterator's current object is valid or not
    if(this->currentIterator.getCurrentIndex() >= this->currentIterator.getSize())
        return false;

    if(!this->currentIterator.getCurrentObject())
        return false;

    //Step 4 : Remove object from iterator and add it into the list
    cCollisionUnitInstancePtr instPtr = this->currentIterator.remove();
    if(!instPtr)
        return false;

As you can see from the above, the code snippet may look simple, but the steps immediately highlighted the rationale behind writing the codes that represent it below.

If there’s a problem, at least I have a firefly hovering around as comments to help guide me to a possible problem.

At the very least, if the codes are implemented accordingly to the comment’s description, I can move on to the next method in the flow.

3) Comments are written only for codes with design flaws

This statement is debunked by my point of view for the 2nd statement. Coming to the notion of design flaw itself, the word design itself can be disputed.

Which level of design are we talking about?
1) Technical?
2) Code?
3) Data Flow?

What flaws are we talking about? Just because someone wishes to make things clearer for everyone, this someone has a design flaw??? What kind of bullshit is this?

Code comments, in terms of the steps I’ve mentioned above, help himself as well as others remember how things are done.

Just one thing, why is coding called coding? Why are codes called codes?

Hey stupid, the reason is because codes are not easily understood! That means in any case, whether you’re an experienced C++ guru or a newbie in C++, it always suck to read other people’s codes. It’s a matter of how long it sucks that’s all. Nobody will feel good reading codes that are poorly documented even if they follow a standard coding and naming convention.

Conclusion

In conclusion, comments and documentations are an absolute necessity in ANY development, software or not software.

The reason is not to make the source code convoluted, rather, it’s meant to clearly indicate why was it done that way.

Remember, a technical code requirement can be done with multiple approaches and chances are if they’re good enough, they’ll satisfying the requirement as well.

For this post, the question in perspective should be changed.

Instead of asking whether codes should be commented or not, one should ask what has to be commented?

With this, I leave this notion for your own consideration. Disagree if you must, feedback if you want to.

Have a great week ahead!

Signing off,
Jeremy