We finally agreed on the defaults...

It might not be much but after several attempts in the past months we've finally came to an agreement about how we should set the sensitive defaults of the software engineering discipline at ?eská spo?itelna and drafted as the first step some guidelines for our software engineers / developers.

Inspired by a workshop we've done with Jürgen De Smet ?? when I had the opportunity to meet and learn from him on the topic of #LeSS we've designed a 3h workshop to achieve what we couldn't in the last more than 2 years - to come to an acceptable agreement throughout our company and different tribes / domains / contexts about how we should define "technical excellence" to significantly improve our codebase and stay true to it in the future.

The workshop was meant to be a collaborative session in order to achieve the agreement and it was attended by about 40 software engineers and senior developers from all corners of the company. After a short ice-breaking introduction and an exercise to start the creative juices going imagining the future state of our company from the technical point of view we've moved to brainstorming and sharing ideas about how the engineering discipline should look in the near achievable future. We've worked in groups and once the brainstorming was done we've moved to discussion-free filtering of each other groups ideas based on our personal feeling of what the discipline and excellence should look like eliminating everything that was not so certain.

What was left afterwards was the agreed upon achievable minimum - notes on practices, techniques, metrics, patterns and principles that would be the shared engineering baseline for the future months.

I am proud to share the outcome of our workshop with the community with a disclaimer that it is just the first step representing what level of software engineering discipline we want every team to achieve in the following months. Some teams are further down the road than others but what matters is we now have a common understanding and we can focus on how to get there and helping each other. We've established an internal technology radar inspired by 思特沃克软件技术（中国）有限公司 and Zalando . We are now creating some minimal #standards and #playbooks for each tech-stack / platform used in our software engineering in accordance to this generic guidance. We are tuning the tools and platforms in such a way to support the endeavour and restarted the #DevOps program focussing on the platform engineering and enablement of teams (inspired not only by #teamtopologies).

What I'm trying to say is that in 2-3 years we believe that ?eská spo?itelna can be a leading software engineering company on the Czech market and not only among financial institutions.

We understand the importance of such move forward to achieve our company's strategy. We also have in essence support from our CEO Tomá? Salomon , our COO Martin Kobza and our head of engineering and platforms Tomá? Metz as well as other tribe and engineering leaders like Pavel Betak , Tomá? Foltyn , Patrik Jerabek , Jan ?alena . So keeping fingers crossed :-)

Also if you'd like to participate feel free to join us as our doors are always open for new colleagues.

You can find the following materials in a PDF.

--- as drafted and later validated based on the workshop notes ---

Main guiding principle

The expected result of great engineering and technical excellence is that "the master branch is always in shippable state, with every commit". Ideally it means that teams deliver consistently high-quality and secured shippable software increments and the business can press anytime a "red magic button" and ship the current state to clients / users (including starting related processes at the same time - marketing, client communication, etc. = so it's business driven shipping).

Coding and clean-code guidelines

We shall consistently produce high-quality code with every commit following the clean-code recommendations making it long-term maintainable, readable and well-structured for the developers that will have to handle it after us.

We enforce these principles by continuous collaboration and the peer review practice (code review) in any suitable form (formal review, pair-programming, mob-programming) and create an audit trail of this by leveraging the pull-request mechanism.

We apply the principle of "the boy-scout rule" to continuously refactor and improve our code (including legacy) as we go rather that taking "the big bang approach".

We make all of this as simple and automated as possible taking advantage of the tools and the industry / community best-practice and recommendations as possible over re-inventing the wheel.

We make the founding fathers of the software engineering discipline ( Robert Martin , Martin Fowler, Kent Beck, Dave Farley , ...) proud with every commit we make.

High-cohesion and low-coupling on all levels

We shall apply the principles of high-cohesion and low-coupling well known from clean code to the architecture of our systems as well - on all levels.

Every level of abstraction of our systems shall be encapsulated (hiding it's internal details) and provide a clean contract as a single unified way to interact with that layer (any kind of API). The higher the level of abstraction, the more stable and long-living the contract. We favour by-default the isolating of the business domain behaviour from the infrastructure and other dependencies by such abstract layers (f.e. using ports and adapters).

On inter-app / system communication (system integrations) we recommend moving to asynchronous integrations based on event contracts (with business domain semantics) generally consumable by any system willing to do so.

We favour taking "the emerging architecture" approach encouraging to delay the "embedment in stone" of architectural decisions as late as possible until we empirically validate them (by research, by experimentation, by data). Also we favour not re-inventing the wheel thus creating custom technical solutions only when empirically proven necessary (and such decisions should be re-evaluated periodically).

The mentioned empiricism should always be written down for further reference and be as close as possible to the implementation (ideally in the version control system next to the implementing code itself). We strongly recommend the usage of the well-established ADRs (architecture decision records). We shall use the same approach when diverging from the recommended defaults mentioned here.

Fast quality assurance and acceptance feedback loops

We understand that the overall quality assurance process is an essential part of the software delivery and an useful feedback loop that needs to be as effective and fast as possible while providing enough confidence (once passing) that everything works as expected.

In order to achieve such state we shall decouple our tests from the implementation details as much as possible by making the code testable by design. We strive for tests testing the abstracted layers through the contracts (APIs, behaviour tests) and leveraging fast tests without any external dependencies as much as possible (concept of "the testing pyramid"). For that purpose we shall use the test-driven approach as a design technique to create such decoupling.

To make sure the testing suite builds the continuous confidence and safe-zone to make changes these tests need to be fast (using test doubles rather than dependencies, I/O) and non-flaky (don't require change if implementation details change).

We acknowledge the importance of higher-order automated tests (in comparison to isolated unit tests - integration tests, e2e tests) but these should be complementary and validate "the plumbing" rather than concrete functionalities with all possible variations. The same applies for non-functional testing suites (security / penetration testing, performance testing) and manual QA like exploratory testing which should be run separately when needed to provide additional feedback.

DevOps, cloud readiness and automation of delivery processes

The outcome of development should be built and semantically versioned artefacts stored in the binary management system as the single source of artefacts / dependencies being deployed to our environments, most notably production. These artefacts should be unmodifiable once built and stored in the binary management system. The same artefact should be runnable on various environments including the cloud environment (ideally take advantage of containerisation and the 12-factor principles).

We shall automate every routine operation in the delivery and deployment process to avoid the risk of human error, to have a full audit trail of every change for compliance purposes and to make things instantly reproducible. The automation (CI/CD pipelines and it's individual parts) should follow the same software engineering principles as regular application development and should follow the open/close principle (open for extension, closed for modification = we expect to have an opinionated unified pipelines consumable as-a-service but be able to extend them with new steps / functions / checks / operations).

What can be described by code or metadata should be done so using the industry standard ways over custom implementations (f.e. Kubernetes templates, OpenAPI, Helm charts, Terraform scripts, etc.) to ensure we can take advantage of the well-established standard tooling and orchestration.

We strive for a fully-automated deployment and propagation into production requiring no human / team interaction after approving the code (code, configuration, descriptive metadata) via a pull-request into version control.

Continuous learning and up-skilling

We as software engineers understand that we need to learn continuously new skills, practices and tools to be able to approach problems in an empiric ways. We use research techniques and technical experimentation (technical spikes) to gather enough information (data) before making a decision.

We establish open "communities of practice" (available to anyone in the organisation) around technical domains or specific problems / issues / missions to share knowledge and support each-other. We actively support the culture of sharing knowledge and hands-on help not only inside the team (to increase the bus-factor), but also between teams (short-term rotations of experts for 1-2 sprints where their expertise is required).

We acknowledge that the best way to learn is "by-doing" thus we establish the pair- programming / mob-programming practice as an effective way to share knowledge and mentor colleagues acquiring new skills. We also take advantage of katas / dojos to acquire, share and practice our skills.

Agile software delivery (iterative incremental product development)

Apart from standardising the software engineering guiding principles (above) we understand that our way-of-work requires the following changes to make the engineering modernisation possible and to gain the benefits from the resulting higher technical excellence.

We strongly believe that the best way to move forward in software engineering and delivery is through the adoption of the values and principles of agile software delivery.

The standardised engineering practices require more resources in the short-term (and initially time to learn them) but the whole organisation will benefit from this investment in the long-term.

We should gradually empower engineers to make product decisions based on empiricism thus increasing product ownership. We should require that every product small increment brings value to the stakeholders and transparently validate this hypothesis with them thus enabling incremental product development rather than big projects.

We should continuously improve on the feedback loops (technical and non-technical) via team and product retrospectives with actionable improvement steps to be implemented as a result with each iteration. We should strive to identify and attempt to eliminate all inefficiencies and wastes in our delivery process through the "inspect & adapt" approach one step at a time.

We as software engineers commit to actively participate in this continuous improvement process with all our expertise.

Dangling themes and items

There were other individual themes and items proposed on the design workshop that will require some more detailed look into in the near future...

We acknowledge that the proposed principles (sensitive default way of software engineering at ?eská spo?itelna) will be a live document improving as our maturity progresses and as the industry changes.