Comments considered harmful

At school, I was taught to comment my programs well. Today, I wonder why I should.

Every comment relating to the code itself is redundant. Redundancy creates inconsistencies, and inconsistencies are a serious threat to code quality. So I prefer not to comment.

"Hey, come on! How do you expect anybody to understand your program if you don't comment it?" I hear being shouted at me. I will ask the opposite question: Why should I write such a lousy program that it needs comments to be understood?

I worked in a group where the coding guidelines said: Comment every class, comment every method. I refused. I mean, as an example, look at this getter, generated by the Refactor -> Encapsulate Fields... operation of NetBeans:

    private String name;
    /**
     * @return the name
     */
    public String getName() {
        return name;
    }

What does that comment add that I did not already learn from the method name? So rather than commenting a method, I prefer to use the comment,  kind of, as the method name. That guarantees consistency and also propagates the "commented" intent to every place the method name is referred to. Far superior to a localized comment!

Martin Fowler once said: "Any fool can write code that a computer can understand. Good programmers write code that humans can understand." I strive to be one of them.

Naming the opposite of actual...

What if a formal parameter does not have the precondition != null? I have started to try out aBookingOrNull, like in

private void UpdateFrom(Booking aBbookingOrNull)

You may argue that this is just the complement of anActualBooking, so one of them is redundant. Instead, I could use either of the couples

• aBookingOrNull vs. aBooking (or just booking)
• aBooking (or just booking) vs. anActualBooking
  

I agree. But seeing aBooking (or just booking) on its own, it is not intuitive which of the couples I have settled on. So, for the time being, I prefer the couple where each of the two alternatives is explicit:

• aBookingOrNull vs. anActualBooking
  

Precondition Naming Pattern

As a dedicated fan of Design by Contract, I search to maximize the value of what I see as its two major contributions, communication and verification. The problem is that i.e. C# does not support executable comments. Information to a client programmer may be specified in a summary comment (will appear in a tooltip) and verified by a Debug.Assert, like this:

/// <summary>
/// Pre: booking != null
/// </summary>
private void ConnectTo(Booking booking)
{
    Debug.Assert(booking != null);
    ...

However, this introduces an undesired redundancy. So how to convey in particular method preconditions to a method caller without this reduncandy?

The technical precondition actualArgument != null is very common. Perhaps a naming pattern or naming convention might do, for instance anActualWhatever, the "actual" part stressing that the variable should actually refer to an object. I could get rid of the informatory comment, since the same information is conveyed through the name of the formal parameter:

private void ConnectTo(Booking anActualBooking)
{
    Debug.Assert(anActualBooking != null);
    ...

I think I will test this idea for a while.