Natural Coding Standards

[Peter_Breen]

Hi All,

Just wondering if anyone there has any documented coding standards for developing in Natural ?

[Matthias1 (Matthias)]

I never defined coding standards, because they were already existant (and ignored by the programmers).

But I would say, the most important things are:

1. Each Natural-Code should be preceded by a standardized commentary block containing the name of the programmer, date, change history, a brief description of the code.
2. Write good inline commentaries about the most important things (like transaction logic etc.)
3. Changes in the code should be marked with a start and an end tag. The tag is a link to the change history. The following way turned out to be useful in our case:

* Change history:
* 2006-07-18    Matthias    added some new code             <001 />
*
THIS IS SOME 
OLD CODE
<001>
THIS IS 
SOME NEW CODE
</001>
HERE COMES SOME 
OLD CODE AGAIN
ONLY ONE LINE OF NEW CODE WAS INSERTED HERE /* <001 />

4. Define standards for field-names. Database-Fields and Global-fields should be recognizeable by name. So it’s easier to find all programs which are using a particular field.
   Don’t use different names for the same business case. For example: Don’t say “invoice_date” and “billing_date” for the same thing.

Less important (but good to think about) are standards like:

5. SUBROUTINEs should be coded at the end of a program or in an own copycode.
6. ON ERROR blocks should be coded at the beginning at a programm or in an own copycode.
7. The END-SUBROUTINE statement should be followed by a commentary containing the name of the subroutine.
8. LABLES for read-loops etc. should be coded in an own line.

[Wilfried_B]

Matthias, it is very dangerous to answer such a question, as everybody has his/her own coding standards. And of course, these are the best standards in the world .

I have to disagree, too (because of maintenance experience) but also to agree:

1. agreed!
2. agreed!
3. no! If you do this and a code is very often changed, it becomes unreadable. Try not to do what a cvs should do! Instead give a good comment in the header what (and why!) you changed the code.
4. agreed! And also define the standard that field should always be qualified (level1-name.fieldname). Then define a unique prefix or suffix for level1 names to avoid naming conflicts.
5. Why? If you are a former pascal programmer, you would expect the routines at the beginning. Ok, you should have conventions about the positioning of subroutines. Why not sort them by name?
6. Why? I would expect the on error at the end of the program.
7. No, unless the syntax checker does not check this. Subroutines are often copied and the name is changed (but not the END-SUBROUTINE comment). So another source of misunderstanding.
8. Why? Does it have advantages over coding the label in the same line as the database access statement? But agreed, use labels instead of line number references.

[Matthias1 (Matthias)]

[quote="Wilfried B

[Douglas_Kelly]

These are my standards for report programs (copied from another discussion…)

A useful arrangement for a Natural report program - organize the code somewhat the order it would be laid out on a page:

• write title/footer - common page elements (page numbering, date, corporate name, etc)
• extract data (find/read/read work/etc)
• sort highest to lowest fields
• at start of data - initialize and first “subheadings”
• at top of page - page heading
• if break of highest field - subheading
• if break of next field - subheading (repeat as needed)
• detail lines
• at break of lowest field - subtotals (use OLD, COUNT, SUM functions)
• at break of otherfields - more subtotals
• at break of highestfield - subtotal for highest break
• at end of data - report summary totals

Some notes:

• you can write a number of reports by using the (n) notation against each WRITE/DISPLAY/PRINT statement. So, you could output detail report to (1), summary report(s) to (2), (3), etc. in same pass of the data.
• DISPLAY statement includes automatic headers. The first DISPLAY statement for the report (n) present in the code (not the first executed DISPLAY) sets the columns and column headings. Typically the DISPLAY is used to produce the detail lines.
• use T* notation from WRITE statements to line them up under the DISPLAY columns. Useful from the subtotal AT BREAK / AT END OF DATA sections to line up tallys under the appropriate columns without counting spaces. Sometimes I put the DISPLAY in a subroutine to allow it to set the column headings and widths but not necessarily be executed (omit detail for a summary report).

[Tobias_Bartl]

1. Something about the definiton of variables:

wrong:

1 #VAR1         (A15)
1 #VAR5             (A) DYNAMIC
1 #VAR3    (A1)
1 #VAR2                            (A15)
1 #VAR4         (N4/1:12)

right:

/* map
1 #VAR1           (A15)
1 #VAR2           (A15)
1 #VAR3           (A1)
/* calculate
1 #VAR4           (N4/1:12)
/* workfile
1 #VAR5           (A) DYNAMIC

I sort them alphabetically and in a row. I also group them when they in similar use (one group for a map, one for calculating, one for workfiles etc.). It is easyer to read, in my opinion.

2. Using constants where it is possible.
3. Using IF instead of DECIDE when there are not so much conditions and if its possible (performance).
4. Using same variable format in a operation, when it is possible (performance).
5. In a decide statement, sort the conditions after the propability. So that the programm must not work around everything or most of your statement with a high probability.

[Bamuhrez]

Hi,

I was searching the web for some reference materials for Natural coding standards and I found Documentation Set which includes:

NATURAL Field Naming Conventions

NATURAL Programming Standards

NATURAL, User Interface Standards

in the following site [url]http://www.lava.net/~mhodges/[/url]:

The documents are in WordPerefct 5.1 format, whoever you can open it using WORD 2003. Hope this will be useful.

Abdullah

[Karlheinz_Kronauer]

Hello Abdullah,

the link is not working correctly,
can you please point us to the right documents.
many thanks,

Karlheinz

[Peter_Reale]

I did a search for these docs, and believe I found them hosted on a different domain …

http://www2.hawaii.edu/~mhodges/index.html

But, based on the Last Updated date at the bottom of the page, and the recommendation to use Netscape Navigator 2.0 for best viewed, I’m not sure how up-to-date the content is.

Pete

---

Systems Analyst veteran
(Natural newbie)

[Ralph_Zbrog]

As a Natural newbie you’ll want to read everything written about the language. The difficulty will be to determine which advice to embrace and which to ignore.

Years ago a User Group president collected and distributed a list of technical tips. For every tip that started with “always,” there was a contradictory tip that started with “never.” And, many tips have to do with personal preference. Just look at the previous posts in this thread.

The quality of such advice corresponds to the breadth and depth of experience of the author. A good place to start is the lists of presenters at the Natural Conferences, many of whom give their advice on the SAG-L listserver. Several more gurus subscribe to these forums, but you’ll determine for yourself who they are.

As a rule of thumb, good advice will start with “consider” and then explain the circumstances under which the tip should be followed or avoided.

And finally, consider the age of the advice. Does it apply to your version of Natural?

[system]

Golden rules I follow:

DONT USE:

1. External Subroutines
2. Processing rules
3. LDA’s with partial views shared between unrealted objects
4. GDA! … use AIV’s instead

DO USE:

1. Copycode with parameters
2. OPTIONAL + BY VALUE parms
3. DYNAMIC’s
4. Internal subr to structure code
5. #prefix for internal variables
6. X Arrays
7. Use AIV’s with object prefix, so thay are like VB static’s
   etc …

Object Naming standards:

XXYYYYTN

Where:

XX = System prefix, eg TM
YYYY = code for object, eg UPDT
T = object type
P = PROGRAM
B = BATCH PROGRAM
M = MAP
F = FORM
N = SUBPROGRAM
S = EXTN SUBR
C = COPYCODE
J = JCL
T = TEXT
L = LDA
A = PDA
G = GDA
H = HELP RTN
etc
N = Number seq 0…9 A…Z

So our object is:

TMUPDTN1

[Alexbj]

[quote=“Matthias”]

@"Wilfried B?5. Why? [...

7. It’s better to extend that point: The programmers should think about putting a commentary after END-tags, if the regarding block is very big. That includes END-IF, END-DECIDE, END-FIND, END-READ, etc. That makes huge codings more readable. Imagine a nested if-structure:

IF condition1 
  /* many lines of code
  IF condition2
    /* many lines of code
  END-IF /* condition2
END-IF /* condition1

A comment pointing when a if statement ends is a potential source of confusion if the code is changed.
Instead of using comments, use the command “struct display”. It shows the beggining and end of every if, for, repeat and define subroutine.

[Ralph_Zbrog]

Response deleted - I should learn to check the posting’s date before responding!

[Peter_Thorn]

I have yet to find anywhere that has managed to retain official Natural Coding standards for very long because coding standards tend to be very idiosyncratic.
For example I always have the label on the same line as the command (it irritates me beyond belief when the label is on it’s own line, because you have to put the breakpoint on the label not the command). I also HATE using special characters (such as <> ^ and but that is because many years ago these special characters were not printed correctly on chain printers causing me grief when trying to debug someone elses bad code (ie not my perfect code).

There is also the fact that Natural is a moving target, and each release could require new techniques that may be contrary to the current standards.