Supported by
Supported by Inetum

A comment on comments

images/thumbnail.jpg - Thumbnail

We learn in school that all code should have comments. Then, in real life, we find that not everyone was paying attention to what was said in school. As a consequence, most code is obscure and without proper comments.

I was always careful to comment every relevant step of my code, specially the parts which are obscure or not self-explanatory.

But since I recently read Uncle Bob’s Clean Code , my opinion on this changed. Today I believe that the less comments the better. And yet, I don’t see this as contradictory to what I used to think.

The logic I’m now adopting is: whenever I feel that a comment is needed, that means something needs to be encapsulated in a method. Let me show it to you.

This is how I used to do it:

METHOD process_clients.
  DATA: t_kna1 TYPE STANDARD TABLE OF kna1.
  FIELD-SYMBOLS: <s_kna1> LIKE LINE OF t_kna1.

* Select clients
  SELECT kunnr name1
    INTO CORRESPONDING FIELDS OF TABLE t_kna1
    FROM kna1
    WHERE kunnr IN r_kunnr.

* Display clients
  LOOP AT t_kna1 ASSIGNING <s_kna1>.
    WRITE \ <s_kna1>-name.
  ENDLOOP.
ENDMETHOD.

And this is how I do it now:

METHOD process_clients.
  display_clients( select_clients( r_kunnr ) ).
ENDMETHOD.

And then I create these two new methods:

METHOD select_clients.
  SELECT kunnr name1
    INTO CORRESPONDING FIELDS OF TABLE rt_kna1
    FROM kna1
    WHERE kunnr IN r_kunnr.
ENDMETHOD.

METHOD display_clients.
  FIELD-SYMBOLS: <s_kna1> LIKE LINE OF it_kna1.
  LOOP AT it_kna1 ASSIGNING <s_kna1>.
    WRITE \ <s_kna1>-name.
  ENDLOOP.
ENDMETHOD.

As you can see, the code in these 3 methods is now self-explanatory and any comment is now unnecessary.

Thanks to this approach, nowadays my mode has much less comments and yet, is much easier to understand. I still use comments: whenever I need to explain how an algorithm is working, why I took a specific approach or whenever I find that some extra context is helpful.

I still hear a lot of people saying that a method only makes sense when it is going to be reused. Nonsense. And I still hear a lot of people saying a method with just one line of code is not worth it. More nonsense.

Greetings from Abapinho.