This website is strongly guided by best practices and the Standard for Public Code published by the Foundation for Public Code which deals with the development and maintenance of code in the public sector as well as with general quality criteria for software. This site provides guidance on how participants can use Open CoDE securely.
These principles are intended to enable users to create better, more easily maintained code; to generate more added value through their own contributions and to address security issues related to their contributions. These principles are not binding and may be implemented on a voluntary basis as recommendations for enhancing quality and reducing risks.
The Standard for Public Code establishes a set of criteria which support public institutions and organisations in developing and maintaining software. The objectives, methods and verification options which are considered to be the easiest to apply and the most likely to provide added value for the Open CoDE platform have been taken directly from the Standard for Public Code.
To gain as many contributors as possible for projects on Open CoDE, it is important to strengthen the users’ trust in the platform and the cohesion within the project community.
To achieve these goals, every project should provide a guideline for contributors, for example in the form of a CONTRIBUTING file. This file should explain to developers how they can contribute to a given project. Furthermore, a public roadmap should be available, outlining the project’s main development goals and time frame.
An issue tracker must be made available to all platform users so that they can submit suggestions for improvements. The GitLab issue tracker available in the Open CoDE code repository could be used for this purpose. There should be an option for reporting security-relevant issues via a non-public channel.
To encourage exchange between users and developers, it is helpful to provide communication channels. The GitLab-Issues, GitLab-Wiki and Discourse features available in the Open CoDE code repository could be used for this purpose.
We aim to create a maximum level of reusability and portability within the projects so that others are encouraged to participate in and contribute to one’s own projects, since the code is reusable. This involvement of third parties in turn increases the project’s quality and reliability.
Avoiding redundant developments is also helpful. To achieve this aim, the development of the codebase should always be driven by the idea that code should be reusable in different contexts. In order to keep the potential user base as wide as possible, the codebase must be independent and free of secrets, proprietary, non-open source licences or non-open source code.
Where possible, the needs of more than just one interest group should be included in the project roadmap and the codebase of more than just one group or organisation should be used.
The following indicators may be used to verify whether these aims are being achieved:
The many requirements for newly developed code serve to ensure that the codebase is easy to maintain and that problems can be swiftly identified. Furthermore, new contributors should be able to quickly develop a good understanding of the existing codebase, which makes for a rapid pace of development.
Several criteria should be fulfilled to achieve these aims. It must be possible to automatically test all major features. New contributions to a project must undergo a review procedure (e.g. pull request) and successfully pass all existing software tests. Furthermore, contributions should be kept small and understandable.
Other quality criteria should be continuously monitored. These include source code test coverage to ensure extensive test coverage of the program and documentation coverage to ensure extensive documentation of the code and features. For this purpose, an indicator is (normally automatically) used and displayed on a project-wide basis to monitor compliance with these principles.
Documenting the project and the codebase is essential and reduces the barrier to entry for project contributors and users. It also helps to increase transparency across the project.
Key elements of good documentation include instructions on how to install and execute the source code, examples for the use of core features, and documentation of all features.
Furthermore, it is helpful to provide more general documentation for a broader public, which outlines the project’s high-level approaches. It is also good to provide a stand-alone version which can be populated with test data that are made available by interested parties.
To review the quality and scope of documentation, one can rely on the assessments of stakeholders and professionals who check the documentation for understandability. Another review criterion is whether it is possible to generate documentation from the code.
By using specific licences and public standards within projects, Open CoDE aims to ensure interoperability between systems, guarantee independence from vendors and give everyone the right to view the code, and indicate clearly how users may continue using the code.
For this purpose, it is necessary to ensure that all code and all documentation are released by the platform under a licence which complies with the OSI (Open Source Initiative) requirements so that it is possible to freely continue using, amending and disseminating the code. For all source code, one licence each should be indicated at file level, if possible in the form of a machine-readable licence and copyright header.
Code with a data exchange feature should use a public standard for the data exchange; the codebase should contain a list of all these standards used.
Tools such as REUSE can be used to verify these items.
In addition, we recommend using the English language. On the Open CoDE platform, both German and English are accepted both for programming and documentation purposes. Users are, however, advised to use English; this helps to facilitate collaboration with the European and international user community and the use of uniform terminology in multilingual components within the software stacks.
To create a secure space for collaboration, a set of security principles for the user community is outlined below. These measures for users aim to create a secure space for contributions, reducing the security risks involved in such contributions.
Security risks to users normally arise from the inadvertent disclosure of confidential information such as passwords or tokens or the unintended disclosure of internal information and programs. There is an increased risk if the component concerned is used internally. Technical and organisational measures should be taken to prevent the exposure of secrets.
We recommend the systematic use of secret scanners with open source contributions. Client-side tools such as GitLeaks and Git-Secrets may be used for this purpose.
The risk of users inadvertently disclosing secrets as a result of misconfigurations in the development machines can be reduced by using repository scanning tools such as GitLabs Secret Detection. Please note that token scanners in the infrastructure (including the Open CoDE code repository) can detect the information only during or after the unintended disclosure. This means that for security reasons it is possible to provide an early warning that information has been disclosed but this does not preclude disclosure as such.
Internally used software that is run without established releases involves an increased risk of secrets being disclosed inadvertently since operative adjustments which are required at short notice are often not sufficiently reviewed before they are implemented. For projects that have a high level of internal activity and do not come with any releases, we recommend using at least an interposed repository for short-term changes.
One of the repository’s general recommendations is not to use any secrets, even temporarily, within a Git repository on development machines. Projects on the platform, specifically those involving network communication, should facilitate the use of secrets stored outside the repository and explicitly block, by means of the gitignore mechanism, the configuration files used within the project.
By using interposed repositories such as an internal repository between the developer and the Open CoDE repository, it is possible to prevent direct communication between developers becoming public and to offer a central space for reviews.
The open source projects on the platform are often derived from direct applications at local government level. Internal users of such software should be able to continue using the internal communication path since not all users are aware that the open source repository is public. For this reason, the Open CoDE platform should be used for external communication only.
We recommend that the principle of dual control (all code is reviewed by a second person) be applied to major contributions, i.e. contributions which cannot be displayed on a single screen page, have complex content or were developed on devices containing sensitive data. Especially in cases where major contributions were not necessarily developed solely by the person publishing them, such a check should cover not only the code as such but also the origin of the code to be published, including any comments and the content of commit messages.
In addition to the overarching principles for developing software in an open source environment, various rules on how to write clean code should be respected at the more detailed level. These concern both naming and the formulation of links. The names chosen and the way links are formulated in the source code greatly impact the code’s readability. If they are well chosen, code is easier to understand and its function and logic are easier to discern from the outside.
Naming is crucial for making the code readable for external users. Suitable naming makes it easier to assess a programme’s function and logic.
Variables should be named in a way that clearly indicates their function. Names should be easy to find by using the search function. This means that names such as are not suitable, since they are neither explanatory nor necessarily easy to find with the search function ( may be contained in other names). Names such as are not very informative either.
Implicit comparisons should be preferred over explicit ones. Comparisons with true or false are superfluous and clutter the code unnecessarily.
Using implicit allocations (e.g. allocating a logical value without using if-else-loops) reduces the number of lines of code and improves clarity while decreasing the error potential.
Positive links should be preferably used. This makes for better readability and reduces the cognitive load on the reader.
Using ternary operators reduces the number of lines of code and improves clarity while decreasing the error potential in the same manner as using implicit allocations.
Magic strings/numbers (typically elements that are cached and normally not called up from outside locations) should be avoided. They reduce readability and open the door for spelling mistakes since they do not support auto-completion. Furthermore, they are not a searchable element.
Declaratory language should be given preference over imperative language in order to enhance readability and reduce the likelihood of errors. Declaratory wording indicates the function of a given section of code. Imperative wording shows how a function is executed.
To achieve an understandable, reusable, testable, maintainable and flexible codebase, overarching software development principles according to Robert C. Martin are described below.
The basic principles have the acronym SOLID and are as follows:
The following paragraphs explain what the five principles are about. An additional description including examples of code is contained in the community article and can be viewed [here, external].
Each class or module of a program is responsible for executing exactly one feature. This makes the modules easier to understand and read. It also facilitates maintenance since it is clearer which part of the program is impacted by a given a modification.
Software units should be designed in a self-contained way so that they are open for extensions but do not require modifications to accommodate new features. This ensures reusability and maintainability and makes the program more robust.
Programs must remain executable even if objects of these programs are replaced with instances of their subtypes. This enhances the reusability of software programs and makes it easier to understand their hierarchical structures.
It is preferable to provide many customer-specific interfaces rather than a single all-purpose interface. This results in the decoupling of systems and makes it easier to maintain the programs.
Modules should depend on higher-level modules only. This means that dependencies of internal details such as variables and functions can only be dependent on higher-level abstractions but not the other way round.