Coding Guidelines

[SaschaWildgrube]

No, this article is not a coding guideline. It is a statement on why a coding guideline is needed, which tools to be used to validate compliance and how to integrate it into a mature development and deployment process.

It may appear self-evident to make a coding guideline part of a mature development and deployment process. It is not. Only a few teams or organizations have coding guidelines, and even fewer actively use them. But why is this the case?

Good coding practices are expected to lead to better code, which is easier to understand, easier to maintain, easier to analyze, easier to test, easier to change. Consistency across a code base produces value by itself, since developers can then navigate the code base better and are able to make changes to different parts of the code – those parts they were not actively working on themselves.

A coding guideline may not only describe how specific code details should look like, but it can also describe which automated tests should exist and how code should be structured – which types of functionalities should be implemented where and thus may even go beyond being a guideline for code – but even be a guideline for the architecture.

ServiceNow provides many low-code and no-code capabilities. The outcomes produced with these tools should also be covered in the Coding Guideline. The “Coding” in Coding Guideline should be interpreted as broad as possible.

A Coding Guideline may cover:

• The use or non-use of specific coding patterns (or anti-patterns)
• Error handling
• Naming conventions
• In-code documentation
• Test coverage
• Modularization and how to split things
• …many other aspects

A coding guideline is a set of rules – to which a team has agreed. That points to a very important aspect: Participation. If the Coding Guideline is a law imposed by a privileged small group to control the work of a larger developer population, we should not expect any positive impact.

The coding guideline should be the result of a collective experience of failures and mistakes. The reason why a team uses Coding Guidelines is to avoid making the same mistakes and experiencing the same failures again. The Coding Guideline should be an expression of collective learning.

To make this happen the whole team must have the opportunity to participate and contribute, to have a say in which rules should be applied, and which are not and which exceptions to the rule should be allowed in which cases. For sure, consensus cannot be achieved in all cases – so some form of a decision-making process is needed. Please refer to chapter “Communities of Practice” for guidance.

Once a team has agreed on a coding guideline (and on a process to change it going forward) it needs to be applied. Just writing down what the team intends to do is not good enough. To be straight: the coding guideline document alone will not have any significant impact on the code base. The individual rules described in the guideline must be checked – automatically – by the developer when writing code and as part of every single deployment.

The OOTB platform feature “Instance Scan” provides the framework to build checks that can investigate every single record (of an application) and assess whether it is compliant to the Coding Guideline. Further, the checks and their documentation can be used to generate the Coding Guideline document – making the checks the actual single source of truth of the Coding Guideline. Instance Scan essentially is turned into a static code analysis tool within the ServiceNow platform.

With that being said, the recommendation is to limit the Coding Guideline to statements that can be checked automatically – and hence produce a binary output of either compliance or non-compliance with no room for interpretation.

This is important for two reasons: running an Instance Scan check as part of the deployment pipeline requires a clear decision on whether the deployment should proceed (no findings produced by any check) or not (at least one finding was produced by a check). A developer should get clear guidance on whether the code they wrote is compliant or not – any room for interpretation will lead to ignorance in the long run.

If, however, a check reveals a finding and the developer is yet convinced everything is fine and as it should be, there should always be the following options:

• The intention of the check is valid and agreed by the team, but the implementation of the check does not match that intention, the check must be improved
• The team does not agree on the intention and decides to remove the check
• The team confirms the intention and the correctness of the result, and the developer get all the support needed to refactor the code and the time and support needed to understand the intention and solution

This feedback loop is important for organizational learning and to build awareness and support in the team.

A team does not need to start from scratch with a blank page, there are numerous resources available that can serve as a basis for the team’s Coding Guideline. There are several publications on ServiceNow good practices (not to say “best practices”), numerous publications on JavaScript coding practices in general and even several open-source contributions for check implementations to start with.

However, to integrate the Coding Guideline related Instance Scan checks into the developer workflow and into the automated deployment the following technical capabilities are required (which are not available OOTB):

• Option to run an Instance Scan check on an application that only uses checks related to the Coding Guideline
• Option to run an Instance Scan check on a single application file that only uses checks relevant for the Coding Guideline
• Creation of the Coding Guideline document based on the relevant checks (to be published in a knowledge base, a corporate wiki, or any other knowledge management system)
• Mechanism to ignore specific checks on specific applications (blacklisting checks)
• Mechanism to use specific check only on specific applications (whitelisting checks)

The open-source tool “CodeSanity” has all these technical capabilities and contains numerous implemented checks which embody the learnings of several large teams working on highly complex application eco-systems.

When a new set of checks are applied to an existing code base, the new rules will inevitably clash with the existing code. The team needs to figure out what fits, what they need (and like), where exceptions need to be made for the existing code and where investments should be made to refactor code.

More information about CodeSanity can be found here:

https://www.wildgrube.com/servicenow-codesanity

Wondering how to integrate a coding guideline into a mature development and deployment process?

Read the whitepaper:

https://www.wildgrube.com/download/A%20mature%20Development%20and%20Deployment%20Process.pdf