#2 (IF #Standards = true AND #Good-practice = false) THEN Software Conventions := ‘Virtual’?

And just like that, we’re onward and upwards, I haven’t been this excited since I started a mySpace page. Sadly my original MySpace ceases to be,(though it never really grew legs anyhow, not unless you like Teenage Mutant Ninja Turtles, Pokemon and Full Metal Alchemist).

I can see why this was so popular

This post will be a lengthy one {huge actually including the examples page, I endured several bouts of writer’s block and gout during this update} and there is a LOT to cover – and no doubt more from the debate we’ll encounter after release. Stay tuned as a lot of this will centre back at the referenced example page:

Take a look after reading this blog release {This example page I intend to update frequently after review and further consideration}.


Now this is all about NaturalONE right?

Wrong, this is a blog dedicated to understanding everything to do with NaturalONE and the plethora of other information that goes with it. Rather than jump into the technicalities and specialities of the new found software (which isn’t that new, I think NaturalONE is nearly up to it’s tenth year) I thought we would address something that would appeal to all developers, analysts, architects and screen writers alike. Plus I really want to start the fire going for aggravated response.

Final
I have a feeling this won’t end well…

Standards, We never asked for, we don’t know how we got them, but we’ll be damned if we are getting rid of them

Now I know there will be heavy debate,

  • What is the right way?
  • What is the wrong way?
  • Why aren’t you doing X this way?

The wonderful thing about coding is there is no definitive absolutely correct way to write and stylise your code (method/logic application is another story there, there is DEFINITELY a right way and a wrong way – READ vs FIND… just to start).

There are recommended ways, some examples you’ll find on this site, but ultimately as you gather experience and confidence… beauty truly is in the eye of the beholder when it comes to clean, elegant code.

Imagine that though, leaving something as powerful as computer code in the hands of clumsy humans, let’s not let the machines on to us too much and write it as awkwardly and open to interpretation as we can (at least that’s how I read it when I was an apprentice!)

Yeah, we’ve all been there… credit: https://imgur.com/77zEb

While it is important to be a productive developer, there is much more satisfaction in being an effective, clear, clean, thorough developer (and may I even suggest a deadly sin of pride?) . Small detail in your code (and subsequent commits) shows an advanced level of respect, knowledge and patience. By applying best practice procedure in not only new code you may be creating, but also, in rectifying, adding additional comments, procedures, modularisation (for readability and usability) as you go is the ultimate respect you can give to yourself and your team.

Never skimp on the detail, but don’t get carried away.

It’s like staring into a blank abyss… don’t look too long, it will stare back

You probably already guessed by now but lets start through some of the basics of writing natural code. I’m just going to address some main points that evoke memories of my earlier days, but there is plenty more out there, most is demonstrated in the aforementioned examples page.

Appreciation for harder times

“Now, these kittens, they do not get trained As we did in the days when Victoria reigned. They never get drilled in a regular troupe, And the think they are smartjust to jump through a hoop.”

Back in the day for the original mainframe developers EVERYTHING mattered, I’m sure even the weather outside had some part in their codes productivity and efficiency. The slightest miscalculation or overuse of a variable, and BAM: you’ve lost your punch cards, the order they were in, gained a fresh 100 page memory print out and most likely it’s all because you tried to divide something by zero.

Things have continually improved somewhat dramatically in all processing aspects compared to days gone by (memory, processors, logic handling).

image
Integer application performance (SPECint2000) over time (1985-2010). Credit: The Future of Computing Performance: Game Over or Next Level? (2011)

Scarily, most of our phones now are much more efficient then their coutnerparts in the 80’s (thanks Moore’s law).

We don’t have to check properly if the code we wrote makes sense, we just have to be satisfied the compiler “okays” it. We can run new modules multiple times without fear they’re doing something bad, because even if it is, it doesn’t really matter right? All that matters is I solve the problem.

Even given the advancement of hardware and operating systems, that does not give the justification to write slaphoc haphazard code – stand up and be proud if you develop mainframe code – demonstrate your understanding of applying correct field definitions and efficient logic handling in all aspects of your application (and that does not just apply to code but documentation too).

Simply solving a problem in the quickest way possible, from a copy and paste scenario, which could inevitably be bad practice and without comments or honing in to accurately rectify or improve a problem is not good enough.

NaturalONE is a wonderful enabler, full of potential and lovely add ons which makes things easy to use, but the tool (and language / code itself) should never be abused or taken for granted.

The skills, attention to detail and correct logic application resonate deeply with advanced developer’s worldwide and again shows the ultimate respect for those who are no longer developing with us (by that I mean happily retired or still filling in punch cards).

Punch cards and when big data meant a full filing cabinet
Damn, divided by zero again, why do I keep doing that?

Some key techniques you can apply straight away

Struct, Struct, where for art thou

Good ol struct, that will save us (everyone know struct / ‘reformat code’ magically realigns your code when you’ve written it all over the place).

I must admit, I’m feeling a bit guilt about this but I nearly had to google the command for struct on the mainframe editor – which you should NOT BE USING ANYMORE!

Seriously…

Ctrl+alt+s = Struct in Natural One. This magic little tool automatically aligns and positions your fresh code (along with any other existing problems).

What a mess!
Much better

What about the issues struct does not rectify? – Like alignment still out of shape, missing or overextended methods

You can quickly add a comment in natural one with the shortcut keys (and FYI there will be a blog dedicated to keyboard shortcut mastery)

  • ctrl+7 toggle comments
  • Ctrl+Alt+C to comment
  • Ctrl+Alt+U to un-comment

For ‘manual’ alignment issues though, let’s get it sorted once and for all:


No more space, put it on my tab

Tabs are now preferred in most languages as the identifying structural delimiter for indentation, variable definition, comments and alignment. Period. I mean Tab. *** I have since been notified (check comments at the bottom of this page) that tab indentation may cause problems in Data areas – YMMV so be careful!

There are few key reasons why:

  • less keystrokes for alignment
  • editor inspection comprehension (tabs will be identified as tabs where as space is open to IDE
Notice the tab char recognition

Regardless of which side you are one (remember to always defend the one you pick though), please, try to align your code for readability, control flow clarification and credibility.

Pay no attention to this graph, nothing to see here. Credit: https://stackoverflow.blog/2017/06/15/developers-use-spaces-make-money-use-tabs/

On your marks, get set, Create a template for the top of your new and existing module(s)

And while you’re at it, try to clean up and reformat your existing modules you work on to the new standard.

Templates of course (alongside module version history and even in line comments in code), become somewhat insignificant when you are truly versioning your code properly and using things like Smart Commits. This is something dear to me and I will be covering it extensively in another blog down the line.

There’s a good example in my page #EX1: Program header comment block


What’s in a name

There’s said to be three main names of concern for modules which can be the bane of a developer’s existence.

The name of the module, which is your simple, ordinary everyday name, such as “TEST”, “USR123P1”, “[TYPE][MODULE][99]”

Broken down – They should follow a formal pattern, to ensure easy collective access and readability, as a good starting, something like this is a good way to collate your modules:

“[TYPE/SYSTEM-IDENTIFIER][MODULE-IDENTIFIER][Z/9, 9]”

Some of my web modules follow that premise, e.g.

  • “WSXEN01” – WS = Web Service, XENA = Xenat, 01 = module number
  • “WSXENL1” – WS = Web Service, XENA = Xenat, L = LDA Indicator, 1 = LDA number

Field names should be clearly defined and representational of the data contained, short succinct ‘catch all’ fields do not look good and their original intentions can get lost in translation e.g. ‘TMP-NM’ -> ‘TEMPERATURE-NON-MASS (okay it should have been TEMPORARY-NAME but you get the gist). These focus on fields in DDM’s, GLOBAL’s, LDA’s and PDA’s.

Variable names, while these differ, most Variables are preceded by the # qualifier to indicate significance. Again, try to ensure they are named clearly and indicate their usage. While fields like #I (I2) are commonly used as a counter, sometimes it can get out of hand… (#J, #K, #L, #M …. #Z). Specific counter reference would be clearer e.g. #TRANS-CNT


And the name known only by the module itself, which no human could ever guess, but it itself knows.

AI Is just a little scary

What’s in a type

I won’t go on too much here, it’s all part of basic developer Natural expectations, hopefully you know by now to declare modules for their intentions and fields for their true intentions and the specific max and minimum field expectations.

  • My preference for counters is (accordingly sized) I2 or I4 declarations, these are most efficient.
  • For a ‘flexible’ text field, an (A) DYNAMIC field comes in very handy, use it for a generic compress statement over and over, crimson and clover. But in all other circumstances, try to use a defined max anticipated value. Don’t just make something N10 if it will only ever get to N5.
  • Try to avoid (A) or (N) deceleration for instantiation and handling of (D) Date or (T) Time fields, Natural has fields for that specific purpose, with many magic ways to display or represent them so use them!

Assigning variables := vs MOVE

Time for another face off. Which do you prefer?

In most other languages now, assigning of variables is almost always performed on the right. To help identify the field being assigned to and ultimate reduce the verbose nature of the statement and facilitate correct indent alignment, I recommend adopting the simpler ‘:=’ for assigning where possible.

Of course there are exceptions to the above – MOVE BY NAME is a powerful and simple statement, there are not many easy equivalents in other languages. Depending on the size of your group, this could save a lot of ‘:=’.


When should you use methods and contain cognitive complexity

IF IF IF DECIDE ON FIRST IF ELSE IF IF ELSE FOR IF REPEAT UNTIL IF ESCAPE TOP

Did you get the gist of the above?

How to Manage Brain Overload — Laine Schmidt Coaching
“The sum of the square roots of any two sides of an isosceles triangle is equal to the square root of the remaining side. ” – Scarecrow, Wizard of Oz

Here’s a nice write-up on the subject: “Cyclomatic complexity is a software metric used to indicate the complexity of a program. It is a quantitative measure of the number of linearly independent paths through a program’s source code

As a general rule, which you should apply to all languages, complexity to be limited to LESS THAN 10 (including values for structure and nesting). There is a nice write up on code complexity here: https://www.sonarsource.com/docs/CognitiveComplexity.pdf

Even though the score here is 5, it could probably suffice to lower this more by moving condition3 to a subroutine

Luckily, NaturalONE has the built in smart to help identify loops and methods into nice little packages with + and – signs and an outline viewer.

Magic little +/- now on the side of your code, handy for collapsing and also ensuring not too many
Outline view, it’s interactive too, click on any item

If you start seeing too many + signs… this might be a good time to create some subroutines to break them down and allow you to focus on the specific aspect of that function.


But there’s so much variation.. How do I remember it all?

I know this page could go on forever with good practice, techniques and formalities, so it’s time to draw that to a close and give guidance for some easy to apply techniques to help master code standards and conventions in your daily rituals.

Don’t stress though, there is hope! There are few easy to use tools at your disposal. i’ll list them in the most accessible and easy to apply scenario.

  1. NatStyle
  2. A colleague to review
  3. Sonarqube (DevOps – Code Analysis)

Natstyle

NatStyle is a handy built in which checks for specific vulnerabilities, like unused variables, missing structure, lines too long – it’s perfect for a quick check of code you’re working on to ensure it is safe (and should at a minimum be enforced with any code review). To quickly execute it, the shortcut it Ctrl+Shift+C.

There’s a great tutorial on the web (and also in my example page) to give you a little more information.

https://resources.softwareag.com/youtube-naturalone-tutorials/natural-one-code-style

You can also change NaturalONE settings to target specific problems or omit them. Once you run a NatStyle check, the problems stay in your error log until you rectify them or clear the NatStyle check.

Peer review

This is the tried and tested means of quality assurance since the dawn of programming. Seek out someone with the nous and know how to critique and review your code and documentation. The one failing with this is unfortunately they potentially won’t always be there when you need them, their review tends to favour their personal preferences and there may be new techniques (such as NatStyle / SonarQube or Team determined rules) which will potentially be missed relying solely on ‘rider’ review.

devRant - A fun community for developers to connect over code ...
Maybe he’ll come back and help us as a force ghost?

SonarQube

SonarQube is an excellent tool which assesses code on commit or manual execution, checking for documented rules and code complexity. There is extensive coverage for a range of languages (even COBOL), but unfortunately Natural not quite there yet – Rules can be tweaked to be organisation specific.

There is some early work done by some external companies to try to incorporate SonarQube into Natural code assessment, though this is not open source yet. I understand SoftwareAG are looking into potentially integrating it into NaturalONE / Jenkins automation in the future. See the heading “Static code analysis for Natural with NaturalONE and SonarQube” for a little more information here – https://serviceorientedarchitect.com/german-natural-user-group-meeting-in-november-2018-legacy-coder-podcast-7/


In summary

It’s never easy to make changes, but do yourself a favour, review the current standards in place for your code and documentation and perform a retrospective reflection (individually and with your team) and assess if everything is written and performing at it’s best.

Limit the variation between the look and declarations in your code, research consistently applied formalities (for your organisation and also in combination with information from sites such as this) and most importantly always apply best practice!

Image
Go Planet!

Tip of the blog-berg

On to the conventions I mentioned earlier (I meant the large formal meeting type) – The Software AG International User Group is Going Virtual – First time ever!

I am a big fan of the International User Group Conference, the meet ups facilitated the modern advancement of services for organisations I have been involved with along with accelerating my own understanding and network contacts. I cannot advocate strongly enough that everybody takes this opportunity to be involved and see some ground breaking customer reviews and software advancements if you have never been before.

Ad the very least, as a valued user, you should register in the user group and actively participate in the SoftwareAG forums (no doubt you already have in the past).

I really am missing not going this year, but with all the safety concerns it is for the best. If you enjoy working with Software AG products and want to enjoy the opportunities, company and conversation of passionate, like minded users around the world, I strongly encourage you to personally attend at least once. Each event is an unforgettable experience in beautiful locations in Europe (not to mention Software AG really do look after you with the memorable events).

For more information on the conference, taking place June 15-19 2020 (online):

https://www.softwareag.com/en_corporate/resources/communities/usergroup.html

  • Get the latest on product developments—often before the public
  • Access the broad knowledge base of experienced Software AG customers
  • Develop contacts for ongoing information exchange
  • Discuss and vote on product changes and enhancements
  • Communicate directly with Software AG experts

Next time

Looks like the tab indents finally paid off in this ASCII

Good news that the open source project is full steam and nearing release! I’m sorting out the last of it, but it will be available for public launch soon:

https://github.com/Trentan/XeNat – Feel free to star it.

The first couple of tools will use USER EXITS to LIST specific module object/source criteria right on your own Mainframe. The project will include everything you need to get started. Eventually this will feature a working example which will be hosted in the cloud, talking to a version of Natural and Adabas in the cloud too!

Finally, we will be enjoying our first special guest interview AND i’ll be adding my take on the Software AG International user groups conference. Don’t forget to register if you haven’t and join in the virtual lobby to network with other like-minded individuals.

If you didn’t guess from that, we might be looking at #3 Software AG International User Group 2020 Conference summary … until next time, stay calm, stay safe, keep coding.