Documentation of developments

Toni_Lou

Hello

We all do lots of development on top of the standard Navision Financials objects. I'd like to know how do you make the documentation of such changes. Using the Documentation trigger? In a word processor?


Toni
alou@mazars.es

mfabian

There are some general guidelines which are very useful.
The first on is that every change is reflected by a version number. The version number could look like:

CN2.60.06

where "CN" stands for the customer name, 2.60 for the Navision version and 06 for the change number. In the document section you would sign and document the change:

CN2.60.06
23.02.01/TONI - Validate number in order to update depending fields.

Within the code you comment your changes and comment out (but leave!) the original code:

//CN2.60.06
{orig
Number := otherRec.Number;
}
Validate (Number, otherRec.Number);
//CN2.60.06 - END

You can find further tips about programming standards at http://www.hermida.com/navision/stdprog.htm

Marcus

Dave_Cox

I totally agree with Marcus on the use of the document section and Version Control remarking of changed code, when you finish working on a version remember to Version your objects with the latest version code, unmark them as modified change the date to the current date and set the time to 12:00, this way you can easy see current unfinished work by the modifed flag, also any objects the Customer may have changed.

As for the style I prefer to mimic Navisions Programming Naming Conventions and style.

If I see a new non Navision variable (C/AL Global) called SeviceJnlLine, I know right away that it is a New Table "Service Journal line" for a Service Module Add on.

SeviceJnlLine is more Navision than SerJnlLineRec
NextLineNo is more Navision than VarILineNo

I find Navision Tables, Codeunits, Reports and Forms which fit the new module I might be working on, then I just renumber, rename change the Source Tables or expressions add or delete lines of code, fields etc.

This maintains the Navision Style which in turn makes it easy for other Navision developers to follow.
Same look and feel, button names and shortcut keys.
Some of Navisions own add-on's stray from their style, which can be off putting as you are used to finding familiar things.

I.E NAD 2.60 Warehouse Documents have no Comments, which you expect to find on Documents System wide.

As for the Original Posting you may find Navisions Compare fob usefull its free and on your Navision CD, this will highlight your changes which you can select, copy and paste into word, then add a few lines of text.

And there is the Implus workbench as well.

---

MindSource (UK) Limited
Navision Service Partner

david@mindsource.co.uk
info@mindsource.co.uk



[This message has been edited by Dave Cox (edited 24-02-2001).]

horrigan

I agree with the previous replies.

You should always use the Documentation trigger to describe what you did. You should always add your own version numbers to the shrinkwrapped numbers, e.g., "NW12.10,TIM0.10".

I don't agree with modifying the date time stamp---except maybe when you ship a final version of the mod after adequate onsite testing. (In practice, you rarely get to do enough testing to have a final version. Typically, project managers who aren't programmers give you, the programmer a fairly sketchy outline for the mod. If you are lucky, you may have time to work up a spec, but this is usually based on what the project manager tells you--- and what he or she tells you is based on discussions with personnel at the client site who may or may not be knowledgeable about the shrinkwrapped product. This is especially true in initial installations, and even more especially if you have to do the training at the client site. Even if you have a good training room at the client site, the trainees often miss much of the training because they constantly have to leave to answer the phone, deal with crises, etc.)

Other suggestions:

- NEVER NEVER NEVER delete shrinkwrapped code from the core product. ALWAYS comment it out.

- Always mark the beginning and end of your added code segments with comments.

- When possible, put new code in its own function rather than adding it to existing triggers. Learn how to pass the current record as VAR (a useful trick which is poorly documented.)

- When possible, put new functions in codeunits outside the core codeunits. Get your boss to spring for a few extra codeunits which you can use as function libraries. (Luckily, codeunits are cheap.)

- Always design your code so it can be easily extended, modified, rewritten for other areas of Navision, etc. For exampe, if you make a major change to the Customer table, prepare yourself to have to do the same thing later to the Vendor table.

- On forms and reports, give your new textboxes, labels, etc. numbers OUTSIDE the usual range. When you create an object in the Form or Report Designer, it will be created with the lowest unused ID number. CHANGE that ID number to something much higher. What I did a lot was to assign numbers in the 1000 range for the first group of related objects on the form or report, 2000 for the next set, etc. Why do you want to go to all this trouble? Answer: to avoid conflicts when you have to port your modified form to a new version of Navision.

- Try not to delete shrinkwrapped objects from forms or reports: make them invisible instead whenever possible.


- When you have a noneditable field on a table, go to the trouble of making the textbox (or checkbox) on the form noneditable as well. This saves you from problems if someone (e.g., the project manager I was talking about earlier, or maybe even YOURSELF) goes in and monkeys around with the table with the Table Designer.

I hope I didn't rant too much :-)

---

Tim Horrigan, NCSD
<Horrigan@AOL.com>

Currently in search of new employment!

Certified as a Solution Developer and an HR/Payroll Specialist!

[This message has been edited by horrigan (edited 24-02-2001).]

mfabian

Last but not least: The importance of propper and COMPLETE documentation of all changes in standard objects becomes obvious if you will have to upgrade your customized version to a higher NF version (such as 2.0 to 3.0)!

When I got the job to lift a heavily modified undocumented NF 1.1 solution to 1.3, I needed about three weeks.

One year later when I lifted the now well documented 1.3 to 2.01 I only needed three days!

Marcus

Toni_Lou

Hello again

Thanks for your answers. We are documenting every change made to
the database following those ideas, but writing comments in an
XML-oriented way.

For example, and following Marcus example, in the Documentation
trigger we would use something like

<doc>
<author>Toni</author> <date>23/02/01</date>
<version>CN2.60.06</version>

Validate number in order to update depending fields.

</doc>


In the code we would mark up the ``deleted'' code like this:

{
<deleted>
<author>Toni</author> <date>23/02/01</date>
<version>CN2.60.06</version>
Number := otherRec.Number;
</deleted>
}

And the new code related to the above change like this:

// <added>
// <author>Toni</author> <date>23/02/01</date>
// <version>CN2.60.06</version>
VALIDATE (Number, otherRec.Number);
// </added>


At first it could seem too verbose; but the extra redundacy
introduced allows a parser (written in Java, Perl or wathever you
like) to extract all the modifications marked up this way to
generate automatically the written documentation of a bunch of
changes.


Toni
alou@mazars.es

Dennis_Decoene

Have you written such a parser? If so, would you like to share it with the rest of the world?

---

Dennis Decoene
Navision Software Engineer
http://www.microcomputing.be

fet

For the documentation of the code, we are using a convenient way : every modifications of the code (ie : in a codeunit) are labelled with a name (ie : FET1) which is set as a comment at the beginning of the modification (END FET1 at the end of the modification). In the documentation trigger, we copy the label and we add a detailed description (who ? when ? why ?...). It makes it very easy to find where the changes occured with the find function (just a copy/paste of the label in the documentation trigger and you find where is the modification).
Anyway, that's our way to deal with it and it can be improved but it's very usefull in big codeunit (12,80...).
Bye.

cbradney

We have a policy of documenting in the documentation trigger and in the code. eg.
DNSS CB 010101 - IMPL CODE - coding change description in implementation
or
DNSS CB 010101 - MOD GLOBAL - Added global "newglobal" as a modification
the rest of the options like FORM, CONTROL etc are obvious
and in the code
//<<DNSS CB 010101 (beginning of comment)
//oldcode; (commented out if theres old code to comment out)
newcode;
//>>DNSS CB 010101 (end of comment)

This seems to work very well. I like the idea of an XML tagged system.
Agree with using Navision-like names such as ServiceJnlLine.
Agree that the timestamps shouldnt be modified manually except when creating an addon or returning a modified object to native form manually.
Tim, if your implementations are so up in the air, I think you need to be using more design documentation <img border="0" title="" alt="" src="images/smiles/icon_smile.gif" /> !

---

Craig Bradney
Technical Manager
Deloitte Navision Solutions & Services
Australia
Tel:+61-2-93227796
craig_bradney@deloitte.com.au

Toni_Lou

Hi

Writing some lines of code in Perl to parse (simple) XML-tagged text files is quite easy. Visit http://www.perl.org for general information about Perl and http://www.activestate.com for getting a Win32 port
of the complier.

Yes, we wrote a parser in Perl that reads a Navision object file (in text format) and generates a new file
for every object found. We told Perl to write these files following some kind of LaTeX markup and to take care
of the XML markup added during the development or modification of the objects
(LaTeX is a general purpose formatting language very popular
in the scientific community --- visit http://www.tug.org and http://www.miktex.org for more information, or
ask a friend with a maths or physics degree).

When Perl finishes we have a bunch of small text files marked up in LaTeX. Those files are then compiled with LaTeX to get
a huge cross-referenced PDF file that includes all the changes made to the Navision database.

Setting up Perl and LaTeX systems is not totally trivial (you know, it's free software). The script I mentioned
is very taylored to our needs and oriented to write LaTeX markup as a result. That is, there is no graphic
frontend and there are a few configuration files to play with before it produces something useful.

If someone is interested in
the Perl parser, I would be glad to share the things I found while parsing the Navision generated text object files.


Toni
alou@mazars.es