Developer Guidelines

Abstract

This document explains the coding standards which should be followed when developing software for our platform. Details are also given for integrating with existing software on the platform, how to package your application for our marketplace and how to test your zApp locally whilst running a lighter weight version of our platform.

Version

Version	Changes
1.0	Initial version of document
1.1	Updated Testing section

Table of Contents

Abstract

Version

1. Coding Standards and Guidelines

1.1. Advantages of implementing Coding Standards

1.2. Purpose of Having Coding Standards

1.3. Coding Standards

1.3.1. Limited use of global variables

1.3.2. Standard headers for different modules

1.3.3. Naming conventions for local variables, global variables, constants and functions

1.3.4. Indentation

1.3.5. Error return values and exception handling conventions

1.3.6. Avoid using a coding style that is too difficult to understand

1.3.7. Avoid using an identifier for multiple purposes

1.3.8. Code should be well documented

1.3.9. Length of functions should not be very large

1.3.10. Try not to use GOTO statement

1.3.11. Number per line

1.3.12. Placement

1.3.13. If / else if / else

1.3.14. SOLID Code

2. Integrating with ZDMP Components

2.1. API Gateway

2.2. Integrating with zApps

2.3. Portal Dash-Button

3. Testing

4. Packaging zApp

5. Mini ZDMP

6. Uploading zApp to Marketplace

7. References

Coding Standards and Guidelines

This chapter provides the standards for developing software using ZDMP components. It is very important for the programmers to maintain the coding standards otherwise the code will be rejected during code review. Only the app code which is submitted to our Gitlab will be reviewed, if your app refers to some code outside of the Gitlab we cannot review this code.

Advantages of implementing Coding Standards

Coding guidelines increase the efficiency of the software and reduces the development time.
Coding guidelines help in detecting errors in the early phases, so it helps to reduce the extra cost incurred by the software project.
If coding guidelines are maintained properly, then the software code increases readability and understandability thus it reduces the complexity of the code.
It reduces the hidden cost for developing the software.

Purpose of Having Coding Standards

A coding standard gives a uniform appearance to the codes written by different engineers.
It improves readability, and maintainability of the code and it reduces complexity also.
It helps in code reuse and helps to detect error easily.
It promotes sound programming practices and increases efficiency of the programmers.

Coding Standards

Limited use of global variables

These rules talk about which types of data that can be declared global and the data that can’t be.

- Global variables should be avoided whenever possible.

Standard headers for different modules

For better understanding and maintenance of the code, the header of different modules should follow some standard format and information. The header format must contain below things that is being used in various companies:

- Name of the module
- Date of module creation
- Author of the module
- Modification history
- Synopsis of the module about what the module does
- Different functions supported in the module along with their input output parameters
- Global variables accessed or modified by the module

Naming conventions for local variables, global variables, constants and functions

Some of the naming conventions are given below:

- Meaningful and understandable variables name help anyone to understand the reason of using it.
- Local variables should be named using camel case lettering starting with small letter (e.g., localData) whereas Global variables names should start with a capital letter (e.g., GlobalData). Constant names should be formed using capital letters only (e.g., CONSDATA).
- It is better to avoid the use of digits in variable names.
- The names of the function should be written in camel case starting with small letters.
- The name of the function must describe the reason of using the function clearly and briefly.

Indentation

Proper indentation is very important to increase the readability of the code. For making the code readable, programmers should use White spaces properly. Some of the spacing conventions are given below:

- There must be a space after giving a comma between two function arguments.
- Each nested block should be properly indented and spaced.
- Proper Indentation should be there at the beginning and at the end of each block in the program.
- All braces should start from a new line and the code following the end of braces also start from a new line.

Error return values and exception handling conventions

All functions that encountering an error condition should either return a 0 or 1 for simplifying the debugging.

- On the other hand, Coding guidelines give some general suggestions regarding the coding style that to be followed for the betterment of understandability and readability of the code. Some of the coding guidelines are given below:

Avoid using a coding style that is too difficult to understand

Code should be easily understandable. The complex code makes maintenance and debugging difficult and expensive.

Consider these two sets of code which do the same thing:

And

Even though the top example uses more lines of code, it is more obvious what is happening and all levels of programmers would have an easier time understanding it.

Avoid using an identifier for multiple purposes

Each variable should be given a descriptive and meaningful name indicating the reason behind using it. This is not possible if an identifier is used for multiple purposes and thus it can lead to confusion to the reader. Moreover, it leads to more difficulty during future enhancements.

Code should be well documented

The code should be properly commented for understanding easily. Comments regarding the statements increase the understandability of the code.

Length of functions should not be very large

Lengthy functions are very difficult to understand. That’s why functions should be small enough to carry out small work and lengthy functions should be broken into small ones for completing small tasks.

Try not to use GOTO statement

GOTO statement makes the program unstructured, thus it reduces the understandability of the program and also debugging becomes difficult.

Number per line

One declaration is recommended per line as it encourages commenting and it does not lead to confusing code.

Placement

In a method, declare local variables just before they are needed. This overcomes this problem of a big list of parameters are the beginning of a method and also the use of each variable is clearer.

If / else if / else

Always use brackets with these statements even when they are optional.

SOLID Code

These principles establish practices that lend to developing software with considerations for maintaining and extending as the project grows. Adopting these practices can also contribute to avoiding code smells, refactoring code, and Agile or Adaptive software development.

SOLID stands for:

S – Single responsibility

O – Open-closed principle

L – Liskov substitution principle

I – Interface segregation principle

D – Dependency inversion principle

If you are not aware of how these work in practice, there are many examples online and I would highly suggest that you take the time to research this.

Integrating with ZDMP Components

API Gateway

For the Authorization this is still a work in progress but as of right now, the following details are needed to gain a valid access token and interact with the API gateway.

POST https://keycloak-zdmp.platform.zdmp.eu/auth/realms/testcompany/protocol/openid-connect/token

Body with x-www-form-urlencoded / Content-Type: application/x-www-form-urlencoded

form data of:

client_id : ZDMP_API_MGMT_CLIENT

username : zdmp_api_mgmt_test_user

password : ZDMP2020!

grant_type : password

This will then return some data such as:

{

“access_token”: “eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJUd0Q3R201NG9ucnZ2Q245MWJYanBpT292Vk5wU0dCdEJLNGRZMjdUaXZZIn0.eyJqdGkiOiI0M2EzY2ZjMi0zMzEyLTQ2MGMtOGYyNC03MDI4OTc4MTAzMjkiLCJleHAiOjE2NjU0Nzk5NjYsIm5iZiI6MCwiaWF0IjoxNjY1NDc5MDY2LCJpc3MiOiJodHRwczovL2tleWNsb2FrLXpkbXAucGxhdGZvcm0uemRtcC5ldS9hdXRoL3JlYWxtcy90ZXN0Y29tcGFueSIsImF1ZCI6WyJaRE1QX0FQSV9NR01UX0NMSUVOVCIsImFjY291bnQiXSwic3ViIjoiZTNiODQ1NzUtNDkyMi00ZTljLWI5ZDUtM2E4MTNjMzNiMWFmIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiWkRNUF9BUElfTUdNVF9DTElFTlQiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiI3MjQ2ZDY1MC1hOWZhLTRmODctOGY2Yy02OTU1M2E3YTY5NWUiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbIioiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwiWkRNUF9GdWxsX0FQSV9BY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgWkRNUF9GdWxsX0FQSV9BY2Nlc3MgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwicHJlZmVycmVkX3VzZXJuYW1lIjoiemRtcF9hcGlfbWdtdF90ZXN0X3VzZXIifQ.Tnl2jD4CJtRs9TWMn445yfkIawpfKUbJK2kgpoIJRpVABLW2hKWxSDsbFP6-dZrNdtCXWGggAmPLXz0ep7SmXu0q82wESYYA-Pvgic-sMSSFeJHYUVpWtigxokSiCsJSj7A-lONNH1uLBynueKkT1EfbG8s2mRGrSY0f6P1L7a8W3MJM-Pw6a5jrC0BrEUbWXW0-qqKlLQcKAyKukUp0_dDz3ytMz-qVC2txqT1KwRl-j-WUEV9a6Qkb2mFnvHnFNT_5x3zlpfv11V5iLRH_mkByZfWyJWGdcq0Qo3PMdjWK09NgIBLYOG-i2gATXEXi8berKoHmF14t8IWvQx28xQ”,

“expires_in”: 900,

“refresh_expires_in”: 1800,

“refresh_token”: “eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJlYjJlNmUzYi04NDNjLTQ1OTQtYjgzYi02YWEyNTA1MTU1MzcifQ.eyJqdGkiOiI2YmMyMDZiNS02OTdlLTRhYWMtYTEyZS1jYjE1ZDAwZmNjNDEiLCJleHAiOjE2NjU0ODA4NjYsIm5iZiI6MCwiaWF0IjoxNjY1NDc5MDY2LCJpc3MiOiJodHRwczovL2tleWNsb2FrLXpkbXAucGxhdGZvcm0uemRtcC5ldS9hdXRoL3JlYWxtcy90ZXN0Y29tcGFueSIsImF1ZCI6Imh0dHBzOi8va2V5Y2xvYWstemRtcC5wbGF0Zm9ybS56ZG1wLmV1L2F1dGgvcmVhbG1zL3Rlc3Rjb21wYW55Iiwic3ViIjoiZTNiODQ1NzUtNDkyMi00ZTljLWI5ZDUtM2E4MTNjMzNiMWFmIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6IlpETVBfQVBJX01HTVRfQ0xJRU5UIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiNzI0NmQ2NTAtYTlmYS00Zjg3LThmNmMtNjk1NTNhN2E2OTVlIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwiWkRNUF9GdWxsX0FQSV9BY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgWkRNUF9GdWxsX0FQSV9BY2Nlc3MgcHJvZmlsZSJ9.zJNc_I16kVCFSJgQSR3d6iIMrOfiQc4N_IPX-PXVa2E”,

“token_type”: “bearer”,

“not-before-policy”: 0,

“session_state”: “7246d650-a9fa-4f87-8f6c-69553a7a695e”,

“scope”: “email ZDMP_Full_API_Access profile”

}

You can then use that token in a call such as:

Header will be – Authorization : Bearer access_token

Integrating with zApps

Here we explain our initial plans on how to integrate with other zApps within your zApp.

•Firstly, they add the dependency in the Marketplace/manifest file: that way if you install a zApp that depends on another zApp, you need to buy/install the dependency(s).

•This would require, that all zApps will be single tenant, that is, all zApps get deployed per tenant.

•The zApp will include an env variable in the questions/values file to be able to configure the dependency URL for the zApp.

•Those values will be set during deployment time by the Secure Installation

•There will probably be some naming conventions for the URL, which we are already using but not defined: appid-tenantid.platform.zdmp.eu. So zApp with zapp1 id and tenant1 URL would be zapp1-tenant1.platform.zdmp.eu.

Portal Dash-Button

If you have a front-end browser application then you should integrate the dash-button into your application. This adds functionality to be able to log into the system, check licensing information and also navigate to various components. There is a guide on how to integrate it here:

https://gitlab-zdmp.platform.zdmp.eu/enterprise-tier/t6.4-portal

Testing

All code needs to be tested thoroughly before being submitted to the Marketplace. You should test on multiple browsers/environments with various versions depending on the type of application for which would make sense. You should also test that it works on Kubernetes / as part of the mini zdmp running that locally.

For testing we do not require anything specific, you should be as thorough as you like with your own testing.