DEV Community: Nikola Stojiljkovic

JaCoCo XML to HTML - my new FOSS tool written completely in PowerShell

Nikola Stojiljkovic — Thu, 06 Feb 2025 10:31:56 +0000

I was looking for an HTML generator for Pester's unit tests coverage report XML and couldn't find one which does not depend on 3rd party tools/languages and is completely free.

So, I've built one.

https://github.com/constup/JaCoCo-XML-to-HTML-PowerShell

Key features

Pure PowerShell without dependencies
Code coverage statistics per group, package and source file
Source code coverage with colored lines, automatic source code language detection and syntax highlighting
All supported statistics are covered: instructions, branches, lines, complexity, methods and classes
Dark and light themes
Support for custom themes (Bootstrap or your own custom CSS)
Simple, but rich, well documented configuration (config file) with minimum mandatory fields - exactly 3: XML file, source code directory and HTML destination directory. The rest are pure customization options.
Easy integration with Pester
Mozilla Public License 2.0 (free and open source)

Note: I haven't finished writing all the tests, so it's marked as a "pre-release". My manual testing is confirming that it works on Pester's coverage XML reports, and I've used it on Windows and Linux (Mac testing pending).

Impressions on GitHub Copilot and PHPStorm - March 2023

Nikola Stojiljkovic — Mon, 06 Mar 2023 11:12:53 +0000

After the initial promo year of free access, GitHub released a commercial version of Copilot a while ago. While the price tag isn't anything special ($10 a month or $100 a year), when you consider the fact that there are many tools, services, IDE plugins,... priced at about $10 to $25 a month, the costs quickly pile up. When you add subscriptions which are not work related, it can become a bit overwhelming. So, the question for each subscription service is - is it worth it? Here are my impressions which you may find useful.

Good, not great

First of all, let's set something straight - whatever Copilot can do, it can't be classified as great. It does many things good (or good enough), but not great. You can simply feel the architecture behind the AI in every single code or comment suggestion it makes.

What Copilot does good

The first thing which Copilot does good is writing comments for the already existing code. I am in the process of revisiting and refactoring some old PHP 7.4 code to PHP 8.2, along with the upgrade of Symfony and PHPUnit. There are parts of the code which I remember being exceptionally complex to write and optimize, which inevitably produced code which is difficult to understand now, 2 years from the time the code was written. Copilot is handy in this situation. I only need to open a comment on top of the code, or start a new docblock comment line, and the suggested description is generated. Copilot's suggestions in this case are OK and mostly true, but I do need to read and try to understand the exact meaning of the generated comment, then run through the code and see if the suggestion was right. About 80%-90% of the time it is, but there are cases where it can generate a misleading comment which would make more damage than help if left unchecked. It's important to note that the accuracy of the generated comment does not depend on the size or complexity of the code. It can be 100% accurate for a complex code, but fail on more simple one (and vice versa). Generated comments are more like good and useful guidelines.

Refactoring and rewriting existing code is one of the stronger points of Copilot. If you take a look at Terms of service, you might notice that you're giving the right to Copilot to read and analyze the code of your project and any open tab in your IDE. I can simply feel this being used extensively. For example, if I have two projects opened and trying to rewrite some old code, it will start offering code suggestions based on the currently opened file (tab) of the other project. However, this is a double-edged sword, since it will force suggestions based on the old code. That's fine if I just want to rewrite something and make minimum adjustments (like renaming properties, variables, methods,...), but if I really want to refactor and improve the code, Copilot simply gets in my way with suggestions based on the old code - and it keeps doing it so aggressively that I simply want to disable it until I'm done refactoring. In addition to this, it will almost certainly skip suggesting empty string or array initialization, even if the old code has it and even if it makes perfect sense in the code. The worst part is that it gradually tries to mix the new code with the old one, which does create a solid amount of mess. But, sometimes - it just works perfectly.

If your code follows a certain architecture and is using design patterns extensively, Copilot really shines. After all, it's made to follow patterns. Following a standard for naming classes and methods and using descriptive names can also help significantly, since it's based on a natural language model and can (in some form) "understand" the context and purpose of the code based on names. For example, include "DataProvider" in the name of a class or trait and it will start suggesting code ideal for use in PHPUnit's data providers (especially if your other data providers follow the same architecture and naming patterns). The same goes for value objects, factories, adapters,...

Where Copilot fails

The most obvious fail point is based on the architecture of any ML application today - it's trained on the existing data and will suggest solutions which are the most common for a particular situation. In my case, that's refactoring old value objects to use constructor property promotion and eliminating getters. Neural network behind Copilot is trained on numerous lines of code using getters - and it will almost exclusively suggest getters over direct property access. It does read and remember the code written previously in a class or a method, and will (eventually) adapt and follow my lead, but that's only for that particular file I'm editing at the moment. When I open a new file and start writing fresh code, it will most likely forget the suggestion rules from the previous file. It will simply fall back to the model which it was trained on, until I start rejecting its suggestions again and typing my own solutions.

Code generated by Copilot is far from being reliable. While it does offer some good suggestions, especially if you first write what you want to do in a comment and let it generate the code, it does not have any knowledge of your application, types or objects which you're using. Although sometimes the accuracy of the suggested code really manages to surprise me, there are much more cases where it just spews out garbage which I need to clean up. The garbage does make some sense, when you take into account that Copilot's neural network is based on natural language - not source code. The most obvious example is that it fairly often suggests using properties which do not exist in my objects, but can be seen as logical given the context. Again, it's the same situation as with generating comments - it does manage to provide good guidelines, but the code needs to be checked manually.

While we're at reliability, even if generated code's syntax is correct and it uses a proper set of variables, properties and methods which do exist in my code, the suggested result may not exactly do what I'm expecting. I have tested this while rewriting the old code which does have unit test coverage. About 90% of the time, unit tests, written for the manually written code, will fail for the Copilot generated code, if I let Copilot derive the logic itself instead of just letting it copy the old code. The dangerous side of this is that the generated code, when read as natural language, will almost certainly make at least some sense, but the implemented code will simply not work. I do need to carefully read through each generated code suggestion and confirm the logic behind the code, which might waste more time than simply writing the code myself.

And, lastly, the integration of Copilot, along with JetBrains code completion is a bit clumsy. There are many situations where these two overlap and that can generate some mess. It also doesn't help that Copilot is activated and tries to generate code when typing a space, a tab or a new line (Enter). It really gets in the way of proper code formatting, which is annoying. I'm also having issues with Copilot's code suggestions being added when I don't want them to be added, simply because of muscle memory when typing a well formatted code. However, that's not the problem of Copilot itself, it's a problem of the IDE plugin. Having a dedicated keyboard shortcut for activating Copilot and the ability to disable suggestions until that keyboard shortcut is pressed would be great.

Conclusion

Even though it has some bright moments, after using it for a while on a real project, I am not entirely sure whether it speeds things up or slows the development down. I can not shake the feeling that I need to double check everything it generates, and that can be a bit tiresome. Especially if you take into account the existence of JetBrains own code completion which I can use out of the box without giving it much thought. Sure, JetBrains code completion is a bit more narrow and it can't generate whole blocks of code, but at least it has a proven track record and I simply know that I don't need to check the code it generates at all. I am certain of one thing, though - the workflow when using Copilot, compared to not using it, is completely different.

Maybe the best way to describe working with Copilot, compared to classic code completion, is to paraphrase Kandi from "Two and a half men":

"With JetBrains code completion it's kind of like going on Space Mountain - it's a good ride, but there is never any real danger. With Copilot, it's like being in a backseat of a car driven by a really smart kangaroo - it may go up on the curb a couple of times, but it will get you there."

I will give it one more month and test on other languages, primarily TypeScript, but at the current state - it's not worth the money.

Buying me a coffee, on the other hand, is well worth the money :)

The most efficient way to debug problems with PHPUnit mocks

Nikola Stojiljkovic — Sun, 05 Feb 2023 10:52:40 +0000

PHPUnit can be overwhelming to those who are just learning the basics of programming and/or unit testing in PHP. It is a powerful and robust tool which has been a cornerstone of unit testing in PHP world for many years now, which means it has a huge set of features covering almost any case you could encounter.

One of the most powerful features of PHPUnit are stubs and mocks. They give you the ability to detach the rest of your code from the part which you are trying to test. You can mock anything - from (other) methods in a class you are testing to dependencies, abstract classes or even traits and interfaces.

The first step, of course, is building the mock, and it usually goes like this:

$serviceMock = $this->getMockBuilder(YourService::class)
    ->disableOriginalConstructor()
    ->onlyMethods(['anotherMethodInYourClass', 'yetAnotherMethod'])
    ->getMock();

Apart from the methods pictured in the above example, you also have many others, like setConstructorArgs() and setMethods(), but we will not go deeper into what they do. What is important in our case is that there are many ways of how exactly you are going to create a mock object, which depends on your needs. You may need to mock a set of dependencies, an abstract class, an interface,...

If you are still learning (or even if you don't keep up with the changes between versions of PHPUnit), you may end up "guessing" which set of methods you are going to call when creating your mocks. Even StackOverflow is full of answers like "The following way of creating a mock works for me" - without any information or context provided.

Well, let's provide some context.

PHPUnit, under the hood, is creating a mock class just like you would write any class. It generates source code for the class, trait or interface which you are trying to mock and fills it with mocked property and return values. One of the checks PHPUnit performs is that the generated mock class code is a valid PHP code. This is done with a less known built-in PHP function eval($someString). This function evaluates whether $someString contains a valid PHP code. A bit of warning, though, as the official documentation states: The eval() language construct is very dangerous because it allows execution of arbitrary PHP code. Its use thus is discouraged. If you have carefully verified that there is no other option than to use this construct, pay special attention not to pass any user provided data into it without properly validating it beforehand.

That being said, PHPUnit prepares the source code of the generated mocked class and stores it in a string, which is then evaluated using the eval() function.

If you are getting errors while trying to create or use mocks, you are not sure what exactly is happening under the hood and how the generated mock class actually looks like - there is a way to see the actual contents (complete source code) of the mocked class, during debugging.

The key point to look at is the PHPUnit\Framework\MockObject\MockClass class and its generate() method. In PHPUnit 9.6 it goes like this:

    public function generate(): string
    {
        if (!class_exists($this->mockName, false)) {
            eval($this->classCode);

            call_user_func(
                [
                    $this->mockName,
                    '__phpunit_initConfigurableMethods',
                ],
                ...$this->configurableMethods
            );
        }

        return $this->mockName;
    }

If you set a breakpoint at eval($this->classCode) you will be able to see the contents of $this->classCode which, obviously, contains the complete source code of the generated mock class. The best part is - it's even formatted properly, so you won't have any issues reading it.

You are now free to experiment with different types of mocks and options for their creation, while looking at how exactly your way of creating mocks affects the end result - the mocked object. Have fun!

If you liked the article,...

Mock nested PHP default functions in PHPUnit tests

Nikola Stojiljkovic — Sat, 28 Jan 2023 23:07:30 +0000

Let's say you have the following:



class ComposerFileService {
    public function fetchComposerJsonObject(string $composerJsonFilePath): ?object
    {
        return json_decode(file_get_contents($composerJsonFilePath));
    }
}

To test this method in PHPUnit, use php-mock/php-mock-phpunit library. First, install it with:



composer require --dev php-mock/php-mock-phpunit

The second step is to use \phpmock\phpunit\PHPMock trait in your PHPUnit test class. We can then write a unit test:



/**
 * @dataProvider fetchComposerJsonObject_HappyFlow
 *
 * @param string $composerJsonFilePath
 * @param string $fileGetContentsMockValue
 * @param object $jsonDecodeMockValue
 */
public function testFetchComposerJsonObject_HappyFlow(
    string $composerJsonFilePath,
    string $fileGetContentsMockValue,
    object $jsonDecodeMockValue
) {
    $fileGetContentsMock = $this->getFunctionMock(dirname(ComposerFileService::class), 'file_get_contents');
    $fileGetContentsMock->expects($this->once())
        ->with($composerJsonFilePath)
        ->willReturn($fileGetContentsMockValue);

    $jsonDecodeMock = $this->getFunctionMock(dirname(ComposerFileService::class), 'json_decode');
    $jsonDecodeMock->expects($this->once())
        ->with($fileGetContentsMockValue)
        ->willReturn($jsonDecodeMockValue);

    $service = $this->getMockBuilder(ComposerFileService::class)
        ->disableOriginalConstructor()
        ->onlyMethods([])
        ->getMock();
    $result = $service->fetchComposerJsonObject($composerJsonFilePath);

    $this->assertEquals($jsonDecodeMockValue, $result);
}

Data provider for this test is simply:



private function fetchComposerJsonObject_HappyFlow(): array {
    $faker = Factory::create();

    return [
        'happy flow' => [
            'composerJsonFilePath' => $faker->unique()->word(),
            'fileGetContentsMockValue' => $faker->unique()->word(),
            'jsonDecodeMockValue' => (object)[ 'key' => $faker->unique()->word()]
        ]
    ];
}

In order to properly test this method, we did the following:

$faker in the data provider is simply using https://fakerphp.github.io to generate random data for our tests. It's not that relevant for our example.
We are not using a real file from the filesystem. Unit tests should not do that.
file_get_contents and json_decode (PHP's default) functions are not called directly, but mocked.
We are testing that file_get_contents is getting called once, with the value of $composerJsonFilePath. The return value is randomly generated (by faker), and is irrelevant in the context of testing the file_get_contents function. We'll just need it in order to properly test json_decode.
We are testing that json_decode is getting called once, with the value of what file_get_contents returned.
And finally, we are testing that our method returned the result of calling json_decode.

For more information and examples of mocking and spying on PHP's default functions, take a look at the following libraries:

https://github.com/php-mock/php-mock - a testing library which mocks non deterministic built-in PHP functions;
https://github.com/php-mock/php-mock-phpunit - integrates the function mock library PHP-Mock with PHPUnit;

If you liked the article,...

[PHP Guidelines series] Adapter design pattern + a dangerous workaround to implement Class Adapter

Nikola Stojiljkovic — Sun, 22 Jan 2023 00:07:10 +0000

As announced here, I am working on a series of posts related to good and bad development practices.

Adapter design pattern

The third design pattern covered by this series of articles is Adapter design pattern. The main article, its sub-articles and a solid amount of runnable examples is available at: https://github.com/constup/php-guidelines/tree/master/src/DesignPatterns/Structural/Adapter

Having the ability to use an interface or class, which might come from a third party (Composer) library, and is incompatible with interfaces that your application can use, is pretty neat.

The theory defines a couple of ways to implement the Adapter, however, only one of them is available in PHP - the so called "Object Adapter". Other ways ("Class Adapter" and "Two way adapter") can not be implemented in PHP because they require a language which supports multiple inheritance, which PHP doesn't.

I've come across a couple of resources which are describing a workaround to implement the Class Adapter in PHP (or in any language which does not support multiple inheritance) including a really simplified example. The example looks like it works and does the job, but has a terrible flaw which I have covered (with examples) in the linked repository.

More to come later

While the article and examples are providing a solid coverage of the Adapter design pattern, if observed as a separate concept and implemented on a controlled set of examples, there is also a need to cover it from a different perspective - usage in the real world. There is a couple of things which bothers me regarding Adapter and a couple of other design patterns which deserve separate dedicated analysis. I simply can not shake the feeling that the 24 "well known" and (numerously) repeated design patterns are a bit bloated, and that the Adapter, although useful, belongs to this bloatware. But, more on that later in a separate article.

Enjoy. Comment. Like. Subscribe.

If you liked the article,...

[PHP Guidelines series] Abstract Factory design pattern - and why it's bad

Nikola Stojiljkovic — Sat, 14 Jan 2023 12:42:15 +0000

As announced here, I have started working on a series of posts related to good and bad development practices.

Abstract Factory design pattern

The second design pattern covered by this series of articles is the Abstract Factory design pattern. The main article, its sub-articles and an extensive amount of practical examples (which you can run either directly or from a bundled Docker container) is available at: https://github.com/constup/php-guidelines/tree/master/src/DesignPatterns/Creational/AbstractFactory

Abstract Factory design pattern is one of the 23 well known design patterns covered in many books and online resources. That, however, doesn't stop it from being deeply flawed, poorly named and architecturally inconsistent. Abstract Factory repository section contains:

Theoretical definition of the Abstract Factory design pattern with practical (runnable examples);
Analysis of its name, definition and components;
A viable alternative (Service Bundle) defined in detail and compared to the Abstract Factory design pattern;
Runnable code examples and deep analysis of working with both the Abstract Factory and Service bundle approach through a series of articles on real world use when:
- adding a new property;
- adding a new family;
- adding a new family member;
- adding a new Product;
- adding a new subfamily;
- working with methods common to more than one Product, family and/or subfamily.

All of this and more has been covered in the repository. I will just copy the conclusions here, but you are welcome (and encouraged) to read through the articles in the repository and run through the provided examples.

This is the most comprehensive coverage of actually working with Abstract Factories that you will find online or offline.

Conclusions from the repository

Abstract Factory design pattern seems like a creative and effective way to manage families of products, but it really is not. It is a half-way implemented Service Bundle which has many architectural and practical limitations. Working around these limitations, if at all possible, is difficult and can lead, in many cases, to code quality degradation over time. By using encapsulation, as defined in OOP theory, it also promotes creation of monster classes with multiple responsibilities without any defined, structured way to handle the complexity and modularize the code.

It has an incomplete definition (missing family name property, missing inclusion of Family Resolver in its list of components), and is named contrary to any logic or standards.

Abstract Factory design pattern suffers form architectural inconsistency - it uses and promotes encapsulation, but at the same time recommends treating Factories as special cases (separate services). It is defined as a creational design pattern, but also manages service (functionality) classification as a side effect.

Code architecture is forced to follow a fixed family classification and is not flexible enough to properly support functionality which breaks this classification. Real-world usability is, thus, limited.

It also suffers from unnecessary code repetition.

This article and its sub-articles have demonstrated, through practical examples, that using a Service Bundle is a much more effective, more flexible and more practical way to achieve the same things as Abstract Factory.

If you liked the article,...

[PHP Guidelines series] Final classes as a warning sign

Nikola Stojiljkovic — Sat, 14 Jan 2023 12:12:39 +0000

As announced here, I have started working on a series of posts related to good and bad development practices.

Final classes as a warning sign

The next chapter deals with one of the warning signs in PHP development - final classes.

I am not, in this post, going to go into details on what are final classes and how exactly they are a warning sign. There is a whole article with examples available in the main repository of this series. Let's just say that final classes are functionally useless and can be easily overridden by using a Decorator Design pattern.

The whole article, with analysis and conclusions is available here: https://github.com/constup/php-guidelines/tree/master/src/WarningSigns/FinalClasses

If you liked the article,...

[PHP Guidelines series] Introduction and Factory Method Design Pattern

Nikola Stojiljkovic — Fri, 19 Aug 2022 21:22:00 +0000

As announced here, I have started working on a series of posts related to good and bad development practices.

Introduction to the series

Since this is the first post in the series, I would like to present the format of the posts and examples.

In order to provide direct, usable examples which you can run, and to tie documentation to the code, I have decided to write this series as Markdown documentation inside a Symfony 6 project hosted on GitHub. Symfony 6 was chosen because I simply needed a comfortable framework to present the examples in, but the examples themselves are not related to any framework.

Each covered topic will have examples which you can read, run, or play with directly.

The intended way of using the repository is to use it as an online learning, reference and examples resource, but you are free to clone the repo if you want to actually run the examples. You can either run it locally, if you have PHP 8.1 installed and active, or in a provided Docker container.

The repository is available on GitHub at: https://github.com/constup/php-guidelines

Factory Method Design Pattern

The first covered topic is the Factory Method Design Pattern: https://github.com/constup/php-guidelines/tree/master/src/DesignPatterns/Creational/FactoryMethod

Factory Method Design Pattern is one of the 23 well known design patterns covered in many books and online resources. However, after a deep dive into the theory and practice, I've came to some interesting conclusions.

The knowledge which can be found on the first page of Google search results, has significantly degraded.

Top results from websites dedicated to explaining design patterns are either incomplete, cover only one aspect of the pattern, or are simply wrong. The most important part is - each source explains the Factory Method pattern differently, which can be very confusing to students and new developers.

My intention with this post was to provide a more complete picture, covering the Factory Method design pattern from multiple angles with multiple different implementations.

Factory Method Design Pattern, although well known, is not as good for your code as you might think.

I have covered the theory, provided examples, explained in detail why it's bad and provided a practical alternative. Motivation behind this is to try and root out bad development practices, regardless of whether they are well known and widely used or not.

I hope that you will find this resource helpful. Feedback is welcome.

If you liked the article,...

Announcement: Detailed PHP development practices series

Nikola Stojiljkovic — Mon, 04 Jul 2022 17:04:00 +0000

This post is an announcement of upcoming series of posts. Target audience of the series are primarily PHP and OOP developers in general (although some languages might have different flavors of OOP).

It will be written from a perspective of primarily PHP backend developer with 12+ years of experience working in Magento/Zend framework and Symfony (although I do prefer raw PHP and writing code which is independent from any framework). I have worked on enough both brand new and completely ruined legacy projects that I've started to see multiple patterns of behavior leading to code degradation. It's time to put that experience on paper, summarize and spread the knowledge.

The series will cover a lot of stuff:

Object Oriented Programming in PHP and in general, with a hint of Functional Programming and other paradigms
SOLID principles
Design patterns
Warning signs and bad practices
Good development practices

But, this will not be just another series of generic tutorials with dry information available everywhere else. This will be a focused effort of analyzing software development practices and potential problems in them by running through well known and established principles - and criticizing them to oblivion when and if needed. The reason is simple: many software development practices are dangerous and create more problems than they solve, but they are still being repeated in numerous online tutorials/courses and taught in schools just because they are "well known and established". I'm sorry, but I'm more utilitarian and pragmatic than dogmatic about everything in life, including work and programming. If something deserves bashing and discarding, it will be bashed to hell and forgotten like Google Glass.

Everything in the series will be well documented, covered with arguments, theoretical and practical examples. It will be all available in a GitHub repository along with samples integrated into a Symfony 6 application.

So, feel free to follow me and expect the articles soon.

Cheers!

Technical Alignment Process within Enterprise Application Chain - Part 3 - Running the alignment

Nikola Stojiljkovic — Tue, 21 Jun 2022 07:50:54 +0000

In the previous two articles, we've seen what are technical alignments, who is involved in the process and how Technical Lead's preparations should look. It's now time to wrap the subject up and describe the process of running the alignment.

This article is written from a perspective of a Technical Lead and is intended for Technical Leads, Team Leaders and developers.

The Alignment Process

But first, let's take a look at what we'll need to have at the beginning of the alignment process. From the end of the previous article, we can see that four key things are needed:

An answer to the question: What are we trying to solve?
A list of possible technical solutions.
A page in our project's documentation which describes the problem and potential solutions.
A list of contacts of other teams and a Solution Designer.

When we have all of the above, the alignment process can start. The steps are:

Contact a Solution Designer: The first step of starting the actual alignment process is to contact a Solution Designer and present your idea. A Solution Designer needs to know why you are requesting a change, the rough (high-level) plan of possible solutions and which teams you predicted to be impacted by your solutions. After you provide all this information, ask the Solution Designer to provide an assessment on whether other teams could be impacted. Agree with the Solution Designer on who should organize the first alignment session (you or the Solution Designer). Agree with Solution Designer and your Product Owner whether a support story needs to be created for other teams.
The first alignment session: All potentially impacted teams should be present on the first alignment session. You will present the change and potential solutions in this initial meeting and gather feedback on which systems are impacted. All systems which are not impacted are not mandatory to participate in the future alignment sessions. Those who are impacted will stay in alignment sessions as long as necessary.
Run the alignment sessions until its completely clear to all involved teams what needs to be done and how: The goals of alignment sessions are:

to narrow down the list of possible solutions to the most feasible/best solution for all involved systems. Even if that solution is not the best or simplest for your team, if it's agreed on during the alignment process, your team needs to be ready to implement it. That's why it's important to propose only solutions which are acceptable for your team and for which your team team has an actual implementation plan;
to create an implementation plan for your team;
to create an implementation plan for other teams;
to have enough technical details and requirements for creating user stories which will describe the solution in such detail that all developers would have enough information in the story and can start working on the solution after refinement;

Provide the results of the alignment to your Product owner: Product owner should be able to read and understand requirements for the agreed solution and break down the requirements to individual user stories. If needed, provide help and feedback to the Product Owner about which stories are needed.

What you should have at the end:

Documented clear set of requirements and technical details.
Breakdown of the feature to user stories.

This concludes the series of articles about technical alignments.

Technical Alignment Process within Enterprise Application Chain - Part 2 - Alignment steps - Preparation

Nikola Stojiljkovic — Tue, 21 Jun 2022 07:50:34 +0000

When you need to implement something which has an impact on other systems in the chain an alignment is needed. In this situation your Technical Lead initiates the alignment and leads the alignment process by organizing and running the meetings (technical spikes). For this process to be effective, you can follow some base guidelines outlined in this article.

This article is written from a perspective of a Technical Lead and is intended for Technical Leads, Team Leaders and developers.

Preparation steps for a Technical Alignment

What you need to have before you start: You'll need to have a clearly defined issue, feature or improvement requirement. The key question which you should have an answer for before you start alignment preparation is: What do we need to solve? How should we solve it comes later in the preparation process;
Start it in documentation, update documentation: Your team is probably using some software to collaborate with other teams and write technical and project documentation (Confluence, some type of a Wiki, ...). Technical alignments are usually done through a combination of mail communication and group calls. There is a lot of information flowing during the alignment process which needs to be filtered into development requirements at the end of the process. The easiest way to do it is to have "Meeting minutes" document after each alignment session and to summarize conclusions from mail communication after some part of the solution becomes clear and agreed upon by all involved teams. For this purpose, you'll need a section in your project's documentation where you can put notes and requirements for all currently active technical alignments. Otherwise, your requirements will get lost in e-mails and notes.
Formulate the base of a solution idea: If you need to lead the technical implementation of some solution, it's important to have a clearly defined idea of what and how it needs to be done. It's recommended that developers first investigate possible solutions either through investigating the issue or by building requirements for a new feature/improvement from scratch.
Narrow down possible solutions and be prepared to implement any of them: If there are more than one possible solutions, narrow them down to those which are technically feasible. If you don't like some solution or implementation method or the team is not confident whether it can be done or not - rule it out as a possible solution. When alignments and technical spikes start, you already need to have a clear information on what exactly needs to be done so you can know the impact on other teams/systems in the chain. Proposing a solution which you are not ready to implement only adds confusion to the alignment process. You need to be confident about the solution you are proposing.
Have team meetings if needed: Team meetings and brainstorming sessions for a feature are a great way to clearly define goals and possible implementation methods for a feature. If you feel that the investigation will last for a decent amount of time and can't be done alongside current workload in the sprint, request an investigation user story to be created. The result of the story should be proposals for solutions and it's best to have them documented. This documentation will later serve in the alignment process and creation of a user story (or stories).
Assess the impact on other systems: Once you have a set of possible solutions, you'll need to assess whether your solutions could have an impact on other systems. Don't spend too much time on analyzing whether there is an impact or not. That would become clear on the first alignment session, because team leads from other teams are the ones who need to understand your proposed changes and assess whether it has an impact on them or not. If you even remotely think that some application in the chain might be impacted, include their Technical Lead in the alignment process.
Prepare the list of contacts: A Solution Designer is the first contact that you need to have. Solution Designer is responsible for planning and overseeing implementation of the solution on application chain level. If needed, a Solution Designer will create high level architecture for implementation of the solution for other teams. You will also need contacts of potentially impacted teams and their Technical Leaders.

Tip: Keep the list of contacts in your project's documentation or team collaboration space. All team members should have access to all relevant contacts.

Include and keep the Product Owner updated: Even early in the preparation process, your Product Owner should be informed about the issue/feature that needs to be implemented. The only information that a Product Owner needs are why something needs to be done and whether you have potential solutions for it. If needed, the Product Owner could be asked to prepare an investigation story (for which you'll need to provide an estimate in story points).
What you should have at the end:

What are you trying to solve?
A list of possible technical solutions.
A page in your documentation which describes the problem and potential solutions. You will use and modify this page during the alignment process.
Contacts for other teams or team leads and a Solution Designer.

The next article in the series will describe the actual Technical Alignment process.

Technical Alignment Process within Enterprise Application Chain - Part 1 - What are technical alignments and who's involved

Nikola Stojiljkovic — Tue, 21 Jun 2022 07:50:14 +0000

When working in an enterprise environment with several (or a lot) of applications developed in different languages, technologies or even on different platforms, but still tightly connected to each other, changing one minor thing in one application can have huge impact on the chain. That's why technical alignments exist. But in order for them to exist, you must first have a proper structure within your organization to support it.

Assumptions

Before we start, let's be clear which environment we're talking about here. We are talking about a connected set of web services, business, sales and analytics management software usually combined with one or more front-end facing applications (parts of the system which your consumers will use).

Target audience are team leaders, solution designers or development team members interested in how an alignment process works and who are the participants.

Technical alignments

Technical alignment is a process of making sure that a change in one application will not result in problems or that it doesn't crash some other application in the chain. The more applications there are in the chain, the greater the possibility of a change having an impact on the chain is. Of course, if you have a lot connected applications, teams working on individual applications, no matter how skilled they are in their area, can and will overlook an impact of a change in some other application. If that happens and the technical alignment was not done, the "blame game" is the last thing you want to do because none of the teams technically failed - the process itself was wrong.

A good technical alignment will have one or more meeting sessions between Technical Leaders from each team and a Solution Designer. The result will be an architectural solution for a change which will have a minimum impact on involved applications (in order to reduce development costs) and at the same time be the best possible technical solution (in order to bring value to the system). Sometimes multiple solutions will be possible with different balance between development costs and actual value (or quality) of a solution, so decisions in which solution the company will invest should be coordinated by a business oriented staff - a Change Manager. No matter how many solutions there are after technical alignments are completed, each solution and its implementation method in each affected application should be completely clear to all involved teams. When the business decision is made, the teams should be ready to start implementing what they've agreed on.

Technical Leaders

Flat team structures are bad. In theory, giving your team freedom to decide who will work on which part of application brings more satisfaction to the people involved in development and can work in smaller isolated teams. Having a flat team structure in an enterprise environment, however, only brings chaos and late delivery.

In order to avoid that, a Technical Leader should exist in each team. Technical Leader's responsibility is to have enough knowledge of the application he/she is responsible for to either assess the impact of the change on their own application or know which team member has the most knowledge about that particular part of the application where the change has the most impact. During the alignment process, Technical Leaders are communicating with Technical Leaders from other teams in order to properly implement a change and avoid chain instability or application incompatibility.

Since in a typical enterprise environment you will most likely have applications written in completely different technologies and underlying architectural principles, having a bunch of Technical Leaders throw ideas at each other will usually not result in a constructive and productive conversation. In order to have a productive alignment session with a reasonable amount of time spent, an overseer is needed who can understand each viewpoint from a technical perspective and filter out bad or nonconstructive ideas. That brings us to the role of a Solution Designer.

Solution designers

Apart from the team and a team leader, you'll need a dedicated person who will be in charge of overseeing the architecture of the whole chain (or a part of it which can be logically separated from the rest) and coordinating changes. They are usually called Solution Designers or Architects. Solution Designers must be technical staff with both extensive development experience and great soft skills.

If you have a manager with little to none understanding of the underlying technology behind each application on this position, you will have a lot of well organized but sadly nonconstructive meetings where each team propose their own "best solution" and brainstorm ideas forever. On the other hand, having highly technically skilled person without soft skills will either result in the same chaos as with a manager (if your Solution Designer is a "soft" decision maker) or result in a risk of making wrong architectural decisions in multiple applications because your Solution Designer's "no compromise" decision making approach is a Single Point Of Failure in your application chain. Both of these bad types of Solution Designers can and will cost your company a decent amount of time and money: lost hours on nonconstructive meetings which could have been used to bring value to the project, bad architectural decisions which produce more problems than they resolve, necessity for system overhaul and refactoring in multiple applications,.. you name it.

So what does a good Solution Designer do? A good Solution Designer will organize meetings with Technical Leaders, understand the change from the technical perspective, analyze possible architectural solutions for the change by using his/her own technical knowledge and be open for considering solutions proposed by Technical Leads. A good Solution Designer must be able to ask the most challenging technical questions and continue to drive the communication with Technical Leads until even the smallest bit of unclarity is removed. "Is-this-part-clear?" should be the informal nickname of your Solution Designer. Ultimately, a Solution Designer should be an effective decision maker able to push the architectural decisions to all involved teams.

Change Managers

There are three main dimensions of a technical solution: development cost, technical value and time needed to implement the solution across the chain (or how fast the change will be seen by end-users).

I was going to write a bit about each of these three dimensions, but this article is primarily intended for technical staff (ex. team leaders, solution designers and developers). So, let's just say that a Change Manager takes these three dimensions into account when making the decision on which of the proposed solutions will be accepted.

Conclusion

Now that we have the whole personnel structure ready, the communication and decision making should be more clear and efficient when implementing a change in an enterprise environment. The only thing we need to do now is to prepare and start the technical alignment process. That's something which will be posted in one of the articles in the future.