Presentation of several coding conventions followed by the developers implementing the CYBNITY projects:
Specific annotations are available to link the specification documentations (e.g functional, architecture, security requirement...) managed in other repository than GitHub with the source codes developed as realization of them. - Why it's important: to quickly navigate and control the quality of alignment between the specifications managed in any other tools (e.g Notion tool for Product Requirements Definition, Security control measures and policies, architecture concepts) with the implementation software codes. ### How-to on Java source code The __support framework library__ (dependency defined in parent `pom.xml` of any implementation project) provide specific reusable annotations for add link to requirement managed in an external documentation reference (link based on requirement identifier). The annotation is usable on several source code element types (e.g Method, Parameter, Package...). For example, to add a reference to an architecture requirement (e.g identified as REQ_ARC_10) into a CYBNITY source code package (e.g into a `package-info.java` file): ```java @Requirement(reqType = RequirementCategory.Maintainability, reqId = "REQ_ARC_10") package org.cybnity.infrastructure.technical.message_bus.adapter.impl; import org.cybnity.framework.support.annotation.Requirement; import org.cybnity.framework.support.annotation.RequirementCategory; ``` ### How-to on JavaScript source code #### Installation The [JSDoc documentation generator](https://github.com/jsdoc/jsdoc) for JavaScript language is used (dependency defined in the `package.json` file of Node.js sub-projects) allowing to manage annotations into the JS source codes. Find more help about JSDoc usage on [JSDoc official documentation](https://jsdoc.app/index.html). For example since a Node.js sub-project like web-reactive-frontend: - To install the latest version on npm globally (might require `sudo`): ```shell npm install -g jsdoc ``` - To install the latest version on npm locally and save it in the package's `package.json` file: ```shell npm install --save-dev jsdoc ``` #### Usage - To configure the JSDoc generation, see defined `jsdoc.json` file. - To generate the documentation into a `./documentation/` sub-directory of the project: - Via the script defined into the package.json: ```shell npm run generate-docs ``` - Via npm command line: ```shell jsdoc -c jsdoc.json ``` - To define a custom annotation type: ```javascript /** * Custom data type defining a programming language * @typedef {Object} ProgrammingLanguage * @property {number} id - Language id * @property {string} name - Language name * @property {string} software - Projects it can build * @property {number} year - the year it came to life */ ``` - To use a custom type: ```javascript /** * @type {ProgrammingLanguage} */ const programmingLanguage = { id: 100, name: "Javascript", software: "Websites", year: 1999, }; ```
Specific annotation is also available to add any references to known vulnerabilities (e.g generated by reused external technologies which not was fixed; or regarding a specific security mitigation developed into a CYBNITY component) fixed into a CYBNITY source code and/or configuration file. - Why it's important: some time some vulnerability are not quickly fixed by the technology partners or other open source projects, and CYBNITY program's developers can develop a fix code more quickly (e.g a temporary mitigation solution reducing the threat impact on the CYBNITY software including a dependency to the external problem) during the time for the partner to solve the problem into their software version. ### How-to on Java source code The __support framework library__ (dependency defined in parent `pom.xml` of any implementation project) provide specific reusable annotations for add link to vulnerability declaring by external stakeholder (e.g other software editor) and/or public documentation (e.g Mitre website). The annotation is usable on several source code element types (e.g Type, Method, Local variable, Type parameter...). For example, to add a reference link to a Mitre published vulnerability (e.g identified as CVE-2022-33915) on a java method fixing the problem during mitigation period into a CYBNITY source code file: ```java import org.cybnity.framework.support.annotation.VulnerabilityOrigin; import org.cybnity.framework.support.annotation.ThreatOriginCategory; class X { @VulnerabilityOrigin(originType = ThreatOriginCategory.CVE, originId = "CVE-2022-33915") public methodWhereVulnerabilityGenerateImpact(...) { } } ```
To identify several components executed (e.g processing units) into an environment and/or a context (e.g software layer, infrastructure space), a component logical name is often required by the developer to define static name simplifying its identification (e.g by a logs system; for a resource allocation in setting project; for discovery by other logical software component). For example, a feature processing unit (executed on a Users Interactions Space) that need to be identified as a member of a consumers group (e.g parallel consumers of a same events stream) can be identified by a logical and common group name. Naming convention helpers allowing to standardize the build of labels are maintained in the CYBNITY layers: ### Java component naming convention #### Users Interactions Space's components At the UI layer level, the `import org.cybnity.infrastructure.technical.message_bus.adapter.api.NamingConventionHelper` utility class (as implementation helper) is available to developer to manage a naming convention according to several categories of component types which can have interactions over the UIS