detailed comments in NAV code

Comments

• Options

  AK Member Posts: 226

  2017-11-22

  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.

  0
• Options

  nick_robbo Member Posts: 49

  2017-11-22 edited 2017-11-22

  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);
  

  1
• Options

  latronamarran Member Posts: 24

  2017-11-22

  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.

  0
• Options

  NavNab Member Posts: 181

  2017-11-22

  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.

  0
• Options

  Slawek_Guzek Member Posts: 1,690

  2017-11-22

  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
  

  Slawek Guzek
  Dynamics NAV, MS SQL Server, Wherescape RED;
  PRINCE2 Practitioner - License GR657010572SG
  GDPR Certified Data Protection Officer - PECB License DPCDPO1025070-2018-03

  0