detailed comments in NAV code

mohana_cse06

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

AK

It's pointless to write in plain text what the code is supposed to do. IMHO comments are mostly bad. Even when not using code managing software I only mark my code with a start and end comment.
Exceptions are very rare, e. g. when the code is dependent on various setups and you have to know their values to understand what's supposed to happen in which case.

nick_robbo

Yes agreed, in the best situation, the comment the developer has added is correct.
If not, then it is worthless and will cause confusion.

The code should be written in a way it understandable without comments.
For instance in your example, you could move the code into functions like this...

UpdateStartDateIfNull(StartDate, UseEmploymentDate);
RaiseErrorIfStartDateGreaterThanEndDate(StartDate, EndDate);

latronamarran

imho writing a comment for every single code line, turns your objects into a huge tutorial. it'll not only took a lot of time, it'll also become a burden for developers. maybe it will be useful for juniors, but i don't think it's worth it.

NavNab

Dear all,

I believe this kind of requests comes from persons that are not developers although they want to fully understand the code.

In this case, that person has two solutions:

• DO NOT READ THE CODE! Ask a developer kindly and he will answer all your questions
• Learn C/AL and then read the code.

If the comments are meant to help juniors, then I think it is not the best way to help them.

Joking aside, I hardly believe that developers should use meaningful name for functions as suggested by @nick_robbo . This will be a lot helpfull than 100 lines of comments.

Slawek_Guzek

Hi,

I am all in favour of adding as comments between lines of code, but only sensible ones. I even tried in m company to port into NAV ground a good (imho) TSQL stored procedures writing habit- start the function or block of code by writing a short comment stating what the function is supposed to do, what it takes and what needs to be returned.

It makes no sense to add comments stating the obvious, or repeating almost exactly in plain words what the code is doing.

I am using myself a similar way of commenting in scenarios where the code is not self-documenting or obvious, but I am always trying to include in a reason why the particular code has been changed/added/removed. Maybe not on line-by-line basis, but often before a block of code.

I am also often using functions, often one-liners, just as a way of structuring and commenting my code, trying to clearly distinguish inputs and outputs. Also I am trying to name function after its hmm, higher level funcion (business purpose ?) Taking the @nick_robbo example:

UpdateStartDateIfNull(StartDate, UseEmploymentDate);

I would rather write it like this:

StartDate := GetProcessStartDate(StartDate, UseEmploymentDate);

I cannot see any cons to be fair - as long as the comments add some value - but I would not consider comments in your example as adding anything.

My 0.02£

Slawek