OperatorFabric Community

Use foreach to iterate over an array (instead of for(let i = ..).

Do not use ngFor / ngIf with methods with computing as angular will call these methods very regularly (around ten times per seconds), use instead variables and compute them only when necessary.

ngOnInit() : ngOnInit is called when component is created, the creation is made by the parent component : be careful to check when initialization is done when calling method inside ngOnInit. When the context of the parent component change, it can lead to a new initialization or not.

Prefer using *ngIf over hidden property to hide elements : stackoverflow.com/questions/51317666/when-should-i-use-ngif-over-hidden-property-and-vice-versa/51317774

Do not use console.log or console.error, use specific opfab service : OpfabLoggerService

To give id to an HTML element, please use dashes between words and only lowercase letters. Example id="opfab-feed-filter-publish-date-to"

Always precise the return type of a function except when it is void (Example : getUserName():string)

Always precise the type of the function parameters (Example : setUserName(name : string))

Function shall start with a verb (Example : showAlertPopup())

When the return type is a boolean, the method name shall be a yes/no question (Example : isUserDeleted() : boolean)

Whenever possible use changeDetection: ChangeDetectionStrategy.OnPush in the component decorator to improve performance

Whenever possible use standalone angular components instead of angular modules

Avoid using hardcoded colors directly in CSS or HTML components. Instead, always reference colors through variables defined in ui/main/src/shared/css/opfab-application.css.

When developing a Spring Controller, you do not need to develop unit test, use karate api test (file pattern **/controllers/** is excluded from test coverage indicator in sonarCloud).

Do not use spring annotation (@Autowired, @PostConstruct.. ) in business code to avoid coupling business code with spring framework. This rules is recent so a lot of the business code depends on spring.

Unit test shall not use random values which is considered as a bad practice

Unit test shall not use external resources (database, file system, network, …​)

In addition to the "visible" structure described above, documents are broken down into coherent parts using the "include" feature of AsciiDoc. This is done mostly to avoid long files that are harder to edit, but it also allows us to reuse some content in different places.

Given the number of files this creates, we try to keep header attributes in files to a minimum. Instead, they’re set in the configuration of the asciidoctor gradle task:

asciidoctor {

    baseDirFollowsSourceFile()

    sources {
        include '*/index.adoc','docs/*'
    }
    resources {
        from('src/docs/asciidoc') {
            include 'images/*','pdf/*'
        }
    }
    attributes  nofooter            : '',
            revnumber           : operatorfabric.version,
            revdate             : operatorfabric.revisionDate,
            sectnums            : '',
            sectnumlevels       : '4',
            sectanchors         : '',
            toc                 : 'left',
            toclevels           : '4',
            icons               : 'font',
            imagesdir           : '../images',
            "hide-uri-scheme"   : '',
            "source-highlighter": 'coderay'
}

All files are created starting with level 0 titles so:

In addition to being available as separate documents (architecture, reference, etc.) for the current release, the documentation is also generated as a single page document available for all releases from the releases page. This is also a way to make searching the documentation for specific terms easier, and could be used to generate a single page pdf documentation.

Unfortunately, this entails a little complexity for cross-references and relative links, because the path to the content is a little different depending on whether the content is generated as different pages or as a single page document.

<</documentation/current/reference_doc/index.adoc#card_structure, Card Structure>>

<<card_structure, Card Structure>>

ifdef::single-page-doc[<<card_structure, Card Structure>>]
ifndef::single-page-doc[<</documentation/current/reference_doc/index.adoc#card_structure, Card Structure>>]

ifdef::single-page-doc[link:../api/cards/index.html#/archives[here]]
ifndef::single-page-doc[link:/documentation/current/api/cards/index.html#/archives[here]]

As you can see in the examples above, we are using custom-defined section ids as anchors rather than taking advantage of generated ones (see documentation). This is cumbersome but:

The :imagesdir: attribute is set globally as ../images, because all images are stored under src/docs/asciidoc/images.

In addition to links, it is sometimes necessary to display the actual content of files (or part of it) in the documentation (in the case of configuration examples, for instance). Whenever possible, this should be done by using the include directive rather than copying the content into the adoc file. This way the documentation will always be up to date with the file content at the time of generation.

Source-highlighting is done using Coderay. See their documentation for supported languages, and the AsciiDoctor documentation on how to apply source-highlighting.

Avoid long lines whenever possible (for example, try not to go beyond 120 characters). This makes editing the documentation easier and diffs more readable.

Most links to other OperatorFabric documents should be relative (see above) so they automatically point to the document in the same version rather than the latest version. Links starting with opfab.github.io/documentation/current/ should only be used when we want to always refer to the latest (release) version of the documentation.

If necessary, add the relevant copyright at the top of the file.