Let's make a world wide standard for comments

The use of comments is not required, nor are these comments are standardized when you use them. If you have a client where you are only one of maybe many different developers from maybe many different NSC’s, a even bigger problem. Navision Financials allows you to document your work, but they have no real usable solution to this, nor a standard we can use. Most NSC’s have their own standard for commenting their development. Some NSC’s are focusing on the use of the comments as a way to manage changes in the code. Other are very organized and putting lots of project management information into each modification - i.e. references to the change order / approval number etc. And no real comment/description. Other (AFAIK not many) are really using this as comments are putting in good and describing texts. Some are using the description trigger with reference in the actual code. The ways to do are many. But what is the best way? Here are some keywords: - New fields (both in tables, forms, reports/dataports) - Changed object controls/field properties (both in tables, forms, reports/dataports) - added variables, deleted fields etc. - Changed C/AL code in triggers/codeunits How to handle this? Suggestions please. I will give you my suggestions later. Best regards, Erik P. Ernst, webmaster Navision Online User Group

I will start I comment new fields in Documentation Section NSC-Me-Date Start… NSC-DC-01/01/01 Start… New Field 50000 Field1 code 10 New Field 50001 Field2 Boolean New Field 50003 Field3 Decimal Code Added to “No.” OnValidate New Key Field1,field2 NSC-DSC-End… Code // NSC-DSC-01/01/01 Start… Field2:=Field1<> ‘’; IF Field2 THEN Field3:=0; // NSC-DSC End… I dont version the code but I version the Objects. I add any Menu and Code changes only to the forms Documentation section. I only Comment code changes to Reports and Codeunits adding new variables to the Documentation Section. It would be nice if thee was a commenting tool which inserted the comment lines, where code lines were changed they can add ----Insert---- ----Delete---- so why not comments ? Mmmm! have to look at that one :slight_smile: It is easy with your customer wanting a bug fix to forget a comment! :frowning: David Cox MindSource (UK) Limited Navision Solutions Partner Email: david@mindsource.co.uk Edited by - David Cox on 2001 Mar 27 00:14:34

quote:


nor are these comments are standardized


Not quite true. There are standards on how to document. Example: Your customer is IBM, Your signature is EPE, the NSC is BMI. Customer is working with NF 2.60 and you apply change number 5. So the change should be documented like IBM2.60.05 27.03.01/BMI/EPE - ad comment here. If you want to write a parser however, who filters comments out of the code you have to face some obstacles. 1) Comment for a single added line is usually being written like this:

Validate(amount);  IBM2.60.05
  1. Code which replaces existing code is written like this:

//IBM2.60.05
{orig
myRec.Modify;
}
Validate(Amount);
myRec.Modify(TRUE);
//IBM2.60.05 - END

— The obstacles are: * On one hand the string //IBM2.60.05 indicates that this is a comment. However you don’t know if this comment only applies for this single line or if you have to consider the following lines also as comments until you reach and IBM2.60.05 - END string. * Comments might be added with // or with { :


// Comment line 1
// Comment line 2
// Comment line 3
// Comment line 4

or like this:


{  Comment line 1
   Comment line 2
   Comment line 3
   Comment line 4
}

Another obstacle: If you look closely (very closely) at an exported object file (as text) you see, that it’s relatively easy to track the sections where a comment is found. For example you know that if you find a text like “OBJECT Report 50002 -report name-” you know that you are in report 50002. If you find “DATAITEM” on one of the following lines, followed by “DataItemTable=Table51000;” and later followed by “OnAfterGetRecord=BEGIN” you can easily determine that the comment written here applies to the OnAfterGetRecord trigger for the DataItem 51000 on Report 50002. (I think it’s important to know where a comment was added. The only drawback is the documentation section which is very difficult to track as there is no official header which indicates “Attention the following lines apply to the Documentation section”. That’s what makes it quite difficult to write a parser for documents unless you use a fixed structure such as XML. ------- With best regards from Switzerland Marcus Fabian

Question to you, Dave: 1) You add a function “GetImportantValue” to a table. I assume you add to the documentation section that you have added a new function “GetImportantValue”. Question: Where do you describe the meaning and functionality of “GetImportantValue”? in the Documentation section or as first lines within the function? 2) You add validation code to the OnInsert and OnModify trigger of a table. Where do you comment what you did and why you did it? in the triggers or in the documentation? ------- With best regards from Switzerland Marcus Fabian

quote:


Originally posted by fabian:

quote:


nor are these comments are standardized


Not quite true. There are standards on how to document. Example: Your customer is IBM, Your signature is EPE, the NSC is BMI. Customer is working with NF 2.60 and you apply change number 5. So the change should be documented like IBM2.60.05 27.03.01/BMI/EPE - ad comment here.


I would really like to know who made these “standards” for comments in your objects. It’s true that they have a standard for version listing (like you write IBMI2.60.05 would be an example). But I’ve seen nothing for comments. And if you look at the comments used in the standard system, then you don’t really get any help, because these comments are different. They are descriptions, not change documentations. Best regards, Erik P. Ernst, webmaster Navision Online User Group

When commenting a block of code, prefer to use // START // FINISH <— instead of END so no confusion with BEGIN END Cheers, John

quote:


Originally posted by fabian: Question to you, Dave: 1) You add a function “GetImportantValue” to a table. I assume you add to the documentation section that you have added a new function “GetImportantValue”. Question: Where do you describe the meaning and functionality of “GetImportantValue”? in the Documentation section or as first lines within the function? 2) You add validation code to the OnInsert and OnModify trigger of a table. Where do you comment what you did and why you did it? in the triggers or in the documentation? ------- With best regards from Switzerland Marcus Fabian


Marcus It would not be logical to explain what the Function or code changes do in the documentation just that it is new and exists. N/S do not use version control comments, even at the 2.00, 2,01 level do they? Not even a note in the documentation section. They rely totally on us as developers to look and understand what they have done. How many commented lines are in the standard Navision code?, not even the localisation or sevice pack changes are commented, you are expected to trust the authors. David Cox MindSource (UK) Limited Navision Solutions Partner Email: david@mindsource.co.uk Web: www.mindsource.co.uk

After reading the comments already posted, it seems as if the way in which I document is similar to other NSC’s, but I definately agree that a standard format would be of great benefit to me, especially when you are trying to find out what modifications have been made from one version to the next. This is what I do: When documenting modifications in any object, I use a shotenend version of our company name, my initials and a modification number. However,this modification number is only an increment of the previous modification and does not bear any relation to any other object. So, for example my version number would be ORLDA1.00 and the next modification would be ORLDA1.01. This would then be wriiten down to the documentation of the object and would be followed by the date, a reason for the modification, and possibly what action had been taken. This then looks something like this: ORLDA1.00 - 27/03/01 Format for barcode *****. Changed to format *** Where I had made the change(if the object has code behind or in it), I would then use the following : //***Start ORLDA1.01 “CODE” //***End ORLDA1.01 The problem I have found with this is that it may be tedious and very slow as I would have to do this in each modification that I had made. The benefit of doing this has been that I can track what I have done and why, providing I know which object to look at in the first place. Maybe this is not such a good idea after all, as I do not know what other modifications have needed to be made to the other objects. This is why I agree that a communal solution is a good idea.

Most important for me is to find ALL documentation in the Documentation-Trigger. Like … dd/mm/yy NSC/me **** BlaBlaBla This is a comment with no reference to the code below. For example when i changed a property or inserted a new field … dd/mM/yy NSC/me 01 BlaBlaBla This is a comment that points to a place in the code below. I can find the code quite easy by searching for the reference-string 01. I found it very easy to do upgrading, when really every change is described in this Trigger. The documentation in the code itself is very similar to what was posted by the others before. Richard Edited by - rmotzer on 2001 Mar 27 17:34:10

This last example is very close to what we use:


      // BMI Modification - 2001-03-15 - BMI/CPH-EE - BEGIN
      // BMI Modification - 2001-03-15 - BMI/CPH-EE - END

Of cause the BMI Modification part could be left out, but then I prefer:


      // BMI/CPH-EE - 2001-03-15 - BEGIN
      // BMI/CPH-EE - 2001-03-15 - END

We always have it on the trigger with message like this:


BMI Modification - 2001-03-15 - BMI/CPH-EE

in the documentation trigger. This way we can easily see it when we open the object in code mode. What about documenting new fields or changes to properties on standard fields? We have simply used “BMI/CPH-EE Added” or “BMI/CPH-EE Changed” on the Description property of the field. Best regards, Erik P. Ernst, webmaster Navision Online User Group

Erik, Dave, I learned this method of documentation from a former Navision-DK programmer who later became chief Navision programmer in Switzerland. I admit I have only his word that this is the “Standard” and that I have never seen a written document from NDK about that. (Not surprising as I have never seen a Navision programmers guide either ). But ok, no matter whether it’s a standard or not. Let me try to define some rules how comments have to be documented and then you tell me whether you like that or not: 1) Documentation should contain NSC, Customer, Programmers name, Date, Navision Version, Change-number and of course description. If we define, that the version number contains Customer, Navision Version and Change number (like: IBM2.60.05, hereafter referred to as Version) then we should add NSC, Programmer name and Date to the comment. (such as NSC/FAB/27.03.01 - ) 2.) All comments of the same change should have a same unique ID as to enable a global search. This ID is the Version. 3.) It should be easy (for a parser) to recognize comments as such and to recognize that these comments belong to a specific Version. 4.) Every comment inside the code is started and ended with the version number. Such as //Version { here comes comment } //Version - END or similar 5.) The structure for commenting should be easy to use for the programmer. The easier the structure the more chances you get that the developer really does comment all changes. — Navision recommends to do an increment of the change-number per object. Thus having in Table 36 change 01, 02, 03 etc. I haved worked according to this principle for the last four years and finally came to the conclusion that this is wrong! Why? Well, let’s assume you have to do modifications in 10 objects because of “VAT-Law” In object x you would have change 01, in object y change 13 and in object z change 06. So you have no chance to find all objects modified because of “VAT-Law”. Therefore we proceed differently in the NCS I’m currently working for: 1) The next highest change number will be released (we add a new record in the Changemanagement header table) and applies to all objects. Therefore all objects touched for “VAT-Law” will have the same Version. 2) A Change number is valid per project and programmer until the change is installed at the customers site. — With this background I can definitely tell, which objects have been installed at a specific date, what changes (versions) are included, which programmers were involved and which objects have been changed. Additional rules determine that the filename of the FOB should include the Version-Number etc. (but this would lead too far at the moment). You know, I am really interested to have a global standard for documentation as this would make it easier to have our parser for change management being released as Add-On ------- With best regards from Switzerland

I´d like to discourage the use of {} as they are used for structuring the exported text object, although I know it’s harder to remark all lines with // :slight_smile: Using only // will make a parser of upcoming tools be more reliable. my $0.02, Torsten :wink:

So can we conclude anything by now? The comments must include: - Date - Developer identification (with NSC or other company name) It must be used on the triggers with a begin/end. In the documentation trigger all changes are described eventually with reference to the code (ie. ref#) so that the changes are easy to find. // is better than {} Anything else? Best regards, Erik P. Ernst, webmaster Navision Online User Group

quote:


I´d like to discourage the use of {} as they are used for structuring the exported text object, although I know it’s harder to remark all lines with // :slight_smile:


I disagree with you in this point. I would prefer {} over //. The reason is the parser which has to filter comments for documentation:


//NSC01-05
{ 
  Example 1:
  One comment line
  Second Comment line
  Third Comment line
}


//NSC01-05
//  Example 2:
//  One comment line
//  Second Comment line
//  Third Comment line

Imagine the situation from the point of view of the parser. The target is to have all comments related to Version NSC01-05 filtered and put to the documentation DB. In both Examples the String “NSC01-05” is a clearly defined starting signal saying “I found a relevant comment, from now on you can read comment lines …” … Until? In Example 1 the } clearly states that comments are finished now. In Example 2 there is no such clear end-trigger. Of course you can say: “Read comments until you find a line not starting with //”. True, but the problem starts if you have different developers, some of them commenting with // and others with {}. In order to have the system foolproof, I prefer to have clear starting/ending signals rather than relying on the abscence of a signal. What speaks against {}? Obviously the fact that you want to have the possibility to comment out a large portions of code with {}. However, comments relevant to a parser are usually located at the beginning of a trigger. In many cases the description of a function. Thus commenting the first lines in {} style does not affect the ability to comment out large blocks of code. Conclusion: There are comments which should be added to documentation like the description of a function. There are other comments like a

 
  Modify(True); // run modify trigger

which don’t make sense in a documentation as nobody will understand their meaning without knowing what the code above does. Could we therefore live with the following definition?: comments which must be added to the documentation must be placed in the header of a procedure/trigger and have the form //NSC01-05 { comments } while comments within the code with no relevance to documentation must be documented like //NSC01-05 //comment //comment ------- With best regards from Switzerland Marcus Fabian

I’ve just done a major renumbering exercise for a punter and while importing the resulting text file I found that the use of {} was a real pain. In the past, some developer had used {} in the documentation section to emphasise bits of their comments (no idea why). When importing the text file these caused errors as the system took them to be beginning and end of section markers. It took ages to get rid of them all from a 38MB text file. I agree they are useful for parsers when you export as a text file, just remember it will hurt when you try to import the object afterwards. Cheers, John

The {} vs // isn’t really so important, when you look at the thing people seams to prefer. It’s only in the Documentation trigger, that you really writes text in many lines. So you would able to stay with just one line with:

// BMI/CPH/EE - 2001/03/29 (- reference#) - BEGIN
// BMI/CPH/EE - 2001/03/29 - BEGIN

In general all other comments should be stay in the Documentation trigger! Best regards, Erik P. Ernst, webmaster Navision Online User Group

I agree on the point of using // and not {} if possible. When I have to use {} I would do it like this: {>> Example 1: One comment line Second Comment line Third Comment line <<} I would avoid using START, BEGIN, FINISH or END, and use this in stead: //>>MEMPB1.53 Field2:=Field1<> ‘’; IF Field2 THEN Field3:=0; //<<MEMPB1.53 It is easy to write, read or search for. Best regards, P.Borg Munk EDB-Management A/S

Marcus, I agree regarding a pure “documentation parser” but my intention was to avoid problems for a possible re-import in Navision as the C/Side parser is not that flexible and has proofed in the past to fail under certain circumstances on additional {}. Bye, Torsten

Hello together, i would prefer to do it this way: a) use a list named ‘change list’ in the documentation trigger of each object a.1) use the following information in this list: → a bookmark for jumping to the part of sourcecode → initials of the programmer and nsc → the date when the change has been done → the number of the version of the object like “nsc1.3” → a short description of the change e.g.: change list nsc-name #nsc001 abc 02/04/01 nsc1.3 New Field 55003 in table Customer a.2) refer with each change to this list b) use code comments only with // b.1) begin a comment with a reference to the change list: → //&#nsc-001 where #nsc-001 is the bookmark where you can search for (see a.1 also) b.2) end a comment with a refferece to the change list → //-#nsc-001 b.3) the ‘&’ shows that it is the beginning of a comment b.4) the ‘-’ shows that it is the end of a comment c) use the description property (most control types have this property) → use the bookmark in the property to refer to the change list d) when you change something, then like this way: //&#nsc-001 //old version //UNTIL Rec.NEXT = 0; //new version UNTIL xRec.NEXT = 0; //-#nsc-001 Don’t delete the old version of code, make it a comment! e) Use the Version list to show the actual version of the object This is my version of a paradigma of commenting code in navision. Its a little bit of everything from you, and maybe ist nothing new, but i think my list is complete Marco :wink: Marco Eymer * knk Systemlösungen GmbH Kiel MailTo: meymer@knk.de CallTo: 0049 431-579720