Comments are evil?

Did you read Soren’s last post? You should as it contains a worthwhile standpoint regarding commenting code. And it’s down right clear that Soren abhors commenting code. Even that much that he doesn’t allow me putting a comment to his post!

So here I am ending up on my own blog with a comment on comments that are considered evil. [:)]

… SQUARE(Evil) … [H]

Here I go …

Dear Soren,

I cannot but support your standpoint. Indeed we should all write clear code that needs no comments. It makes it much easier to create, understand and maintain. The funny thing is that we – NAV developers as a group – keep on generating unreadable code; for ages already. And not only those “out in the field”, also at Microsoft. Just have a look a codeunit 80. Even printing the darn OnRun code gives you a fifty pager that will keep you busy for a good number of hours to unravel. Facing that fact we could recon ourselves happy with the comment lines provided here, even if they are “evil”.

So as you validly say “we should try to do better”. I would have left out “try”. We should do better. Simply because we will profit from it and, even more down-to-earth, because we all are paid for it. And as we both know, it’s not that hard. And we are even helped with it. By the Design Patterns project. By the PRS clan. By Design Pattern videos. By Mark Brummel’s posts, like this one on Natural Language Programming (which by the way also declares comments as evil).

And it’s good to know that these are not voices shouting in the wilderness as people are picking this up. Standard NAV code is improving. A vast number of people are watching the videos and attending related presentations. Etc.

As said, I cannot but support your standpoint … in principle.

Yes, I want my code to by minimal and clear. It should not do things that is not asked for. It should not have any artifacts that are redundant, unneeded, etc. And yes, a source management system like Team Foundation Server (TFS) indeed supports me (and you) in this. But …

… I also want to do my work as efficient and effective as possible. And that’s why we use comments, i.e. code markers, to our code when modifying existing code objects. Like most of us do, I know. Comparable to what we did for local features in standard NAV. 

This allows me, looking at the C/AL code,

… to have a quick insight in what changes have been implemented over time. True, TFS will also help me to get this insight, but not in one glance. So I need to do extra actions to get to the same point of understanding.

…, as a developer, to straight forward pinpoint the faulty code change that underlies the error when I am debugging.

…, as a tester, to determine the scope of my white-box testing. What part of the code do I need to take into account in my (new) tests.

…, as a (feature) code integrator, to perform cherry pick merges. For this we even assured that each added field or page control will have a reference to the related TFS work item in the Description property.

I hear you thinking: “Luc, you can do better.”

Maybe you’re right and I am to old to change our practice. Or maybe I am just afraid of change, not daring enough. However, using these practices – our best practices, I dare to say – our work has been profiting from it, and still does.

Your fellow in TFS arms, Luc van Vugt

As Soren states he has “… heard all the arguments …, but it doesn’t change my view that COMMENTS ARE EVIL“, making my exercise without any chance to change his mind, of course. [8-|]

Nevertheless I just wanted to give my two cents on this even if that leaves me somewhat evil. [6]