Skip to content

Software Development Recommendations

New Software Project

Steps in General

These are some common steps when a new software project is started.

  1. Project Conceptualization
  2. Define Project Scope and Objectives
  3. Requirements Gathering and Documentation
  4. Create a Project Plan
  5. Assemble the Project Team
  6. Select the Technology Stack
  7. Develop a Risk Management Plan
  8. Design the Software Architecture
  9. Set Up Version Control and Development Environment
  10. Create a Prototyping or Proof of Concept (PoC)
  11. Finalize Budget and Resource Allocation
  12. Develop a Testing Strategy
  13. Kick-Off Meeting
  14. Establish Monitoring and Reporting

Only thing missing is a step 0, which is a setting up an early project documentation convention.

Documentation is Crucial (Early On)

Why documentation is crucial...

  1. Traceability: It helps ensure that every decision, requirement, and milestone is documented, making it easier to track progress and changes.
  2. Knowledge Sharing: It ensures that all team members, including new members who may join later, have access to the same up-to-date information.
  3. Accountability: With proper documentation, it's clear who is responsible for what task, reducing ambiguity.
  4. Compliance: In regulated industries or environments, proper documentation is required for audits or certifications.

Documentation at Any Level

Work is not done when the software works but when the work is transferable by documentation to other developers using the documentation.

Conventions for Early Project Documentation

Some of the project documentation has no direct relation to the actual source code produced and is stored in a Document Management Systems (DMS) or fileserver having a logical and traceable document-archive directory structure. Also e-mails especially with external stakeholders sending e-mails with important decisions are archived there as well.

Sourcecode Accompanied Documentation

This documentation are merge-able text documents which reside in the source version controlled repository.

Binary documents from office application and pictures like jpg or png must never be used.
Preferred are Markdown files using scalable vector graphics (SVG), PlantUML or Mermaid.

Detailed design is part of the code also are the architectural decisions made. For the latter the "Architectural Decision Records (ADRs)" a system is created using markdown. This solves the problem on older releases having to be fixt according the decisions made for that release.

In Source Documentation

Assumed is that a convention on Code Styling is available and applied.

With in-source documentation is meant:

  • Doc-Block: Describes the usage of an identifier and is harvested for generating developers usage documentation in IDE's or website for easy reference.
  • Inline-Comments: Essential for understanding the code why is written in a certain way. It helps to merge code to decide which change should prevail.

Adding a reference to any document (ADR, IEC or Government Regulatory Standards e.g.) in the code is always helpful.
The reference could also be a reference to a document from the DMS.

A DMS reference is never a filepath or web-link but always a code which can be translated into a filepath using the DMS archiving convention.
To allow the archiving structure to change without loosing integrity from documentation referencing it.

Development and Deployment Environments

General

Testing should simulate real-world deployment conditions. Build processes should be IDE-agnostic to ensure consistent testing results.

Staging Area

Prior to a release deployment, a release candidate undergoes integrated testing in a staging environment which is similar to the final real-world environment.

Docker Environments

Docker can be utilized to set up the necessary environment for testing and development. To maintain reproducibility, package installation should be avoided in Docker container environments during pipeline jobs and real-world operations. If a necessary package is not included in a standard stock Docker image, a custom image should be built and used. Furthermore, using "latest" versions of images can lead to inconsistencies and should never be used.

Unittests & Coverage

Write comprehensive unittests and ensure that unittests cover all possible code paths and edge cases. Use a code coverage tool and measure code coverage to identify areas that need improvement. Strive for high code coverage and aim for a high code coverage percentage but keep the quality of the tests in mind.

Integrate unittests and code coverage into the CI pipeline. Run unittests and measure code coverage as part of the CI pipeline to ensure that quality is maintained throughout the development process.