detailed comments in NAV code

I got a request to add comments like below for each line of code we modify or write

What are your thoughts with pros and cons?

 

IF (StartDate = 0D) AND (NOT UseEmploymentDate) THEN

  StartDate := WORKDATE;   // If Start Date is Null and the user did not check Use EmploymentDate then use the Workdate

 

IF (StartDate > EndDate) AND (EndDate <> 0D) THEN 

  ERROR(error2);    // If Start Date is After End Date and the End Date is not null then Error msg

  • WOW! actually it's a translation of C/AL to plain English for mere mortals (read, not programmers) to understand!

    To me, it doesn't make any sense, it's an overkill. Modifications must be commented, but not to such an extent.
    Only in case of awkward variable naming politics it could be reasonable, that is:

    IF (d31415 = 0D) AND (NOT cb000000017) THEN d31415 := WORKDATE;

    Besides, people not capable to understand from code only what these your 2 sample lines do, actually will never get access to and see the code, too.
  • In reply to Modris Ivans:

    Agree.. Developers like me, prefer reading the code to reading long comments at the end of each line. A small piece of code will become very long in size. If the logic is complex, comments can be added for others to understand; but not for simple logic.
  • Why would you even comment?

    Comments are evil! As my friend Soren Klemmensen said. And basically then I agree. Avoid any comments in code if you can!

    In best case they are correct, in most cases misleading and very often directly wrong.

    If you need to comment your code to describe what it does, then your code needs of refactoring.

    And the comments in your example is just about the worst I have seen (hope they are just made up examples). The code is already clear and easy to read, adding comments makes it less readable, it doesn't really help anything.

    The only thing that I really would change was your "error2" var. That I would make tell you exactly what error you talk about like "StartDateAfterEndDataButNotNullErr".

     

    The only kind of comments, I previously have enforced, was directly change comments with references to the issue/request ID of the project. Like // #321 - EPE >> to // #321 - EPE << - and typically a "change log" in the object documentation header.

    In C/SIDE I typically still uses this kind of comments, but not on projects where we have full source code management.

    But now that we use AL in Visual Studio Code, then as long as you have your projects in Git, then even that last comments can go. Here you see directly in the code, who last changed it, with a description and eventually directly with the git issue reference.

  • It seems to be a tutorial for Non NAV Individuals. It's just a wastage of time as if some development needs 2 hrs and if you follow this then it will take another 2 Hrs. Doesn't find any value, Instead the one who ask you to do so, you can give him separate 1 hr NAV training each day, at least it will add a more value.
Related