Van Vugt's dynamiXs

All around NAV dev and test

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. Smile

... SQUARE(Evil) ... Cool

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 mergesFor 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. Geeked

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

  • +1

    Let's be both evil ;-)

  • I'm with you on this, Luc!

    This post perfectly describes my opinion: www.makinggoodsoftware.com/.../comments-are-evil

    What “comments are evil” really means is that you should always push yourself to use as few comments as possible, not because you are lazy, but because they are not necessary.

  • I completely agree with Luc on comments. They are a necessary evil. They should be as little as possible but sometimes you cannot avoid them when the logic you are implementing is very complicated. And also when a line of comment can save you 10 minutes of studying the code.

    I WANT comment to describe the functions and it's parameters and how to use them. I want the comment in a way so I don't need to read the code in it to understand how to use the function! I HATE losing time because I need to study the code of the function to be able to use it. I don't care about its implementation. I just want to use it and not losing time by using it.

  • And I thought nobody will say anything to counter that post :). I am with you too Luc - saying that all comments are EVIL, is just too radical.

    Even the standard NAV code could use a few comments here and there, so that the newcomers are not overwhelmed by the sea of functionality...

  • ;-)

    I was somewhat surprised too, Vytenis. Do we all agree on this?