Saturday, January 21, 2012

Commenting computer programs rant

So, I think we can all agree that useful comments in programming are good.  Like describing something non-obvious or commenting something that is obvious that doesn't make sense WHY you're doing it.

But seriously, why would you do this:

// Desribes what a Player is
class Player
{
    // the Player's position
    public Vector3 position;

    // the Player's age
    public int age;
}

or even worse


/*
 * Desribes what a Player is
 */
class Player
{
    /*
     * the Player's position
     */
    public Vector3 position;

    /*
     * the Player's age
     */
    public int age;
}


Hello! The comment is completely useless.  And even worse, in the second case, all the work to make the comment look "pretty" is detracting from me being able to actually see what a Player is.

Now if your comment were useful, that would be different:

class Player
{
    // how many times a player has visited each location*
    public map<Location, int> locationCounter;
}

* - still only somewhat useful, but the best I could come up with at the moment

No comments:

Post a Comment