Uniform Development Standards
Posted on 02/02/2024 by Marcin Szymusiak
Uniform development standards are a set of guidelines and best practices that help in creating consistent, high-quality software. They cover various aspects of the development team's work, starting from analytical development, through the implementation of changes, testing them, and deploying them to production, ending with their maintenance.
The development standards at 3e Software House are intended to define the key steps that must be performed in the proper order by all project teams, without delving into details and practices adopted as a supplement to the general standard by individual teams, leaving employees room for freedom and individuality. In our case, uniform development standards create a process that every change goes through, which includes stages such as:
- Analysis
The initiator of any process is always the need to implement some change, whether the change aims to fix a bug or introduce a new feature into the system. Every change must be described in a clear and unambiguous way. The purpose of this phase is to provide that description. Not every change requires the development of full documentation; in many simple cases, a description in the ticketing system is sufficient. However, for more complex changes, the support of an analyst who will prepare a detailed analytical document is necessary. To ensure the appropriate quality of this phase, we have developed an analytical document template that includes a list of key areas that an analyst should standardly verify and describe if the change requires it. Our document template covers topics such as:
- description of project domains
- ecosystem description
- project components description
- description of the project's main functionalities
- user classes description
- description of the infrastructure the project will use
- detailed description of business requirements
- non-functional requirements, including those related to performance, security, maintenance, quality, and legal aspects.
Each point has a description and guidelines that serve as a cue for the analyst, indicating what to pay special attention to. At this stage, having standardized areas for analysis improves the efficiency of analysts' work because the document template ensures that the analyst does not waste time building the document structure from scratch but starts working immediately by filling in the template. Secondly, such a template requires the analyst to pay attention to specific areas, which based on experience, have been classified as key. At the same time, we make sure to update the templates appropriately according to our experiences and changing conditions.
- Development
The primary stage of the software development process. Our development standards at this stage are mainly focused on the proper use of tools offered by the GIT System. Our project standard at this stage includes areas such as:
- Guidelines for working with GIT branches (FeatureBranch), involving creating a new, unique, and clearly named branch for each change. This principle is especially important in projects where releases are built based on dozens of smaller changes. Storing changes independently allows for full freedom in their implementation without the risk that different changes will interfere with each other during development and allows (to some extent) flexibility in choosing the timing of implementing a given change and building version packages.
- Rules for describing changes (individual commits): Years of software development have taught us how seemingly trivial the task of describing commits affects the quality and efficiency at the maintenance stage of the application. A good description of the purpose of the change is especially important when, after months spent on application development, one needs to return to a segment of code, analyze its operation, and understand what changes have been introduced in its area and why.
- Unit Testing Development Requirements: We consider this to be one of the fundamental principles of creating good software. We believe it is not possible to effectively develop any project that does not include unit tests, at least for the main processes. Unit tests, which may seem like an unnecessary effort during the project development stage, pay off very quickly when changes are introduced. Without them, a change in one functionality can lead to changes in other areas. Manual verification becomes very costly and sooner or later, errors that arise in this way will start to leak into production.
- Guidelines for Using CI/CD: In today's world, as applications become more modular, the lack of automation in building and deploying applications becomes a huge burden. Conducting regular releases of an application built on microservices becomes virtually impossible. The project team should not waste time on manually preparing deployments, as such tasks are neither efficient nor safe in the long term - it's easy for a deployment mistake to occur, which can result in a faulty production deployment.
- Principles of merging changes into the development branch and conducting code reviews: Maintaining good code quality should be the foundation of every organization involved in software development. For this reason, our standards also emphasize code review. For this purpose, we have developed a process that every change undergoes before being merged with the main branch of the code repository. Changes made on separate branches, when functionally complete, are submitted for review by other developers (mainly seniors) through Merge Requests and only after approval are they merged with the main development branch. This process aims to minimize code quality issues and the leakage of temporary, developmental debug calls into the final version.
All our project standards at this stage are aimed at improving the efficiency and quality of the software being developed, as well as promoting communication and facilitating the onboarding of developers into new projects. On the other hand, we take care to leave some details under the team's control and respect the individual preferences of developers. It is the team of a given project that decides, for example, the rules for code formatting, its static consistency, and which design patterns to apply to individual changes.
- Manual Testing
Every change must be verified by a tester. This verification has two main objectives: Firstly, to check whether the change prepared by the development team meets all the requirements described in the change documentation, and secondly, to verify that these requirements are correctly implemented. At 3e Software House, the manual testing stage is carried out in two phases. The first verification covers only the individual change. In this part, changes are verified one by one, where the quality of a single change is examined. For this purpose, testers prepare test scenarios based on functional requirements. These scenarios are then manually verified by the testers, and a report is prepared based on them, including a possible list of found bugs.
In the second step, the entire release is verified, meaning all major processes, including the changes that will be deployed to the production environment. The aim of this step is to verify that the introduction of changes has not caused regression in theoretically unchanged functionalities. To verify this stage, testers use general sets of test scenarios, which are used with each deployment. Alongside unit tests, this is another crucial moment when we strive to protect our software from regression errors.
- Production Deployment
The culmination of the software development process is, of course, its deployment to production. This stage is carried out after obtaining the necessary approvals, whether from an external client or from internal departments such as testing and support. Upon receiving approval, the change is committed to the main GIT branch, from which scripts perform automatic operations, such as static code analysis, CI, and CD. In projects that lack such automation, these tasks are manually performed by the developer.
- Maintenance
The final stage is to verify whether maintenance work needs to be carried out on the production server. These tasks include, among others, the removal of old temporary data and backups, and the review of indexes in SQL databases. After completing the last stage of the development process, the change is handed over to the maintenance department.
The developer standards implemented many years ago and still being developed have significantly contributed to the improvement and stabilization of the quality of code produced by us, and have facilitated the transferability of employees between teams. Thanks to these standards, the process of integrating new developers also becomes somewhat easier, as right from the first hours of work, a new team member has the opportunity to familiarize themselves with the rules that will apply to them. We believe that these rules cannot be set in stone and such a dynamic industry as IT requires continuous change in the applicable standards. For this reason, all the procedures we have developed are subject to ongoing evaluation and improvement.