Code comments are DEAD…or ARE they??

We’ve all dabbled with code comments. In fact, when learning programming, it’s one of the first little things you learn.

/**
 * We were all shown how to add our own comments to code, 
 * perhaps on Day 1.
 */
public class MyExample {
    public static void main(String[] args) {
        System.out.println("Really cool, ehh?");
    }
}

Stuff like this is something coding instructors love to show. And it’s cool, right? Write all the commentary you want about your code.

• How it works
• Why you picked this algorithm
• Detailed explanation about HOW that algorithm works, to help you out the NEXT time you have to read that chunk

That last one is key. Why?

Because our ability to read code ebbs and flows. Sometimes, when we revisit a chunk we haven’t seen for six months, getting back up to speed can be tough. A comment explaining the algorithm in HUMAN can be vital.

And this is where comments can sabotage us.

Because what happens when we ALTER the code? What happens when we write a detailed explanation about how it works, but then we change it five times. And when the other person on our team makes a few tweaks of their own?