Forem: Yann Rabiller

Tailwind Alchemist: find all tailwind colors in your codebase

Yann Rabiller — Wed, 04 Feb 2026 15:29:15 +0000

This article was initially published on my blog — sharing here for the Dev.to community.

I love Tailwind. For a long time, I was afraid of CSS and almost didn't want to understand it. Tailwind made me feel like it's not such a big deal after all.

Some people say that they lost their CSS knowledge because of Tailwind, but for me it's the opposite. I'm now curious about it and it feels great!

At some point though, I realized something was quite annoying. When using Tailwind, you put the color (or bg color) directly on the element, which is great to understand quickly how the component looks like, but if you decide to change the theme later, you have to go through all your codebase and change the color names one by one.

I tried to create a design system to avoid this, but I was not that great at finding names and it always ended up in a big mess.

I later discovered DaisyUI, which provides a theme system on top of Tailwind. Instead of using color names like bg-blue-500, you can use semantic names like bg-primary and then define what primary means in your theme.

Changing the theme is then super easy, you just change the color values in your theme definition.

There's one problem though: when you start with some templates (like Flux UI or Shadcn which are used by the Laravel starter kits), you have a lot of hardcoded Tailwind color names in your codebase. Adding DaisyUI later means you have to go through all your codebase and replace the color names with semantic names.

I could not find a simple tool to do this, so I built one: Tailwind Alchemist.

It's made in Typescript and works as a CLI tool. You just give it the path to your codebase, and it finds all default Tailwind color names that are still present in your files.

Here is how you can use it:

$ npx tw-alchemist scan -p 'resources/js/**'      

Found 28 Tailwind colors:

amber-400
black
blue-100
blue-200
blue-700
blue-800
green-500
green-600
neutral-100
neutral-200
neutral-300
neutral-400
neutral-500
neutral-600
neutral-700
neutral-800
neutral-900
orange-300
red-100
red-200
red-50
red-500
red-600
red-700
violet-500
white
yellow-500
zinc-900

If you want to know which files contain which colors, you can add the -v flag:

$ npx tw-alchemist scan -p 'resources/js/**' -v

Found 28 Tailwind colors:

Color: violet-500 (found in 3 files)
  - resources/js/components/AppHeader.vue
  - resources/js/components/AppLogo.vue
  - resources/js/components/MobileHeader.vue

Color: neutral-500 (found in 5 files)
  - resources/js/components/AppHeader.vue
  - resources/js/components/AppearanceTabs.vue
  - resources/js/components/TextLink.vue
  - resources/js/pages/auth/TwoFactorChallenge.vue
  - resources/js/pages/settings/Profile.vue

Color: neutral-100 (found in 3 files)
  - resources/js/components/AppearanceTabs.vue
  - resources/js/components/NavFooter.vue
  - resources/js/components/PlaceholderPattern.vue

Color: neutral-800 (found in 2 files)
  - resources/js/components/AppearanceTabs.vue
  - resources/js/components/NavFooter.vue

...

If you want to know which lines (and which class utilities) contain the colors, you can use extra verbosity with the -vv flag:

$ npx tw-alchemist scan -p 'resources/js/**' -vv

Found 28 Tailwind colors:

Color: violet-500 (3 occurrences)
  - resources/js/components/AppHeader.vue
    - Line 106: text-violet-500
  - resources/js/components/AppLogo.vue
    - Line 10: text-violet-500
  - resources/js/components/MobileHeader.vue
    - Line 28: text-violet-500

Color: neutral-500 (6 occurrences)
  - resources/js/components/AppHeader.vue
    - Line 233: text-neutral-500
  - resources/js/components/AppearanceTabs.vue
    - Line 33: text-neutral-500
  - resources/js/components/TextLink.vue
    - Line 21: dark:decoration-neutral-500
  - resources/js/pages/auth/TwoFactorChallenge.vue
    - Line 100: dark:decoration-neutral-500
    - Line 132: dark:decoration-neutral-500
  - resources/js/pages/settings/Profile.vue
    - Line 244: dark:decoration-neutral-500

Color: neutral-100 (4 occurrences)
  - resources/js/components/AppearanceTabs.vue
    - Line 23: bg-neutral-100
    - Line 32: dark:text-neutral-100
  - resources/js/components/NavFooter.vue
    - Line 28: dark:hover:text-neutral-100
  - resources/js/components/PlaceholderPattern.vue
    - Line 11: dark:stroke-neutral-100

Color: neutral-800 (2 occurrences)
  - resources/js/components/AppearanceTabs.vue
    - Line 23: dark:bg-neutral-800
  - resources/js/components/NavFooter.vue
    - Line 28: hover:text-neutral-800

...

It only supports Tailwind v4. It's also on Context7 so you can ask your LLM (with the right MPC) to use it when refactoring your codebase.

I hope it can be useful to you. If you like it, feel free to give it a star on GitHub ⭐️

A free CI (using Docker-Compose) for your Gitlab repositories?

Yann Rabiller — Wed, 03 Oct 2018 23:18:07 +0000

This article was originally posted on my blog.

If you're like me, you use Github for public repositories and for private repositories owned by organizations, but for your own private repositories, you use Gitlab. Indeed, Gitlab offers free unlimited private repositories and does the job.

After having pushed a lot of commits, you decide that it could be really nice to automate your tests every time a Merge Request (yes, Merge Request. We're talking Gitlab language here) is created.

Then you think that you could use CircleCI as you do for your Github repositories, especially since you know how to use docker-compose on it. You log into your CircleCI account, go to the integration page, and realize Gitlab integration is missing. Github is there, as well as Bitbucket, but no Gitlab in the area. Shit. You can still upvote the idea of a Gitlab integration on CircleCI's website, but until they decide to change things, you're stuck.

You decide to list all the free CI services that can work with Gitlab and match your expectations. And then you realize that Gitlab offers a CI service. After having read all the not clear at all advertised features on the website (to Gitlab’s commercials: you have a nice product, we just don’t realize how cool is your offer since everything is so fuzzy on your website. It’s a shame) you start to think that maybe they offer a free CI even for people using free private repositories on the Community Edition. It seems it is limited to 2000 build minutes per month, which is frankly a very generous deal. Our question today is more precise: is it possible to use docker-compose to build the whole stack and run your tests in the CI? Yup.

First, the (very bad…) documentation says you need to enable some shared runners, but in my case it was already done by default, so I guess you don’t need to do it either. Next.

Now we just need to create a .gitlab-ci.yml file in the root directory of our project. This is quite documented for the general use, but there is no track of docker-compose in the documentation. It seems we just need to install it as a python package (thank you Stack Overflow!) and then we can use it. We also need to use some obscure image:docker and docker:dind services. Well, if it works, why not.

image: docker

services:
  - docker:dind

before_script:
  - apk add --no-cache py-pip
  - pip install docker-compose
  - docker-compose build
  - docker-compose up -d
  # here we can install our dependencies (composer, yarn…)

tests:
  script:
    # launch our tests
    - docker-compose exec php phpspec run --format pretty
    - docker-compose exec php phpunit
    - docker-compose exec php behat

Quite easy actually. I just had some issue (that I don’t have locally or on CircleCI) with the interactive TTY while executing docker-compose exec. Maybe because the version used by pip is the one adding a regression? I dunno. Anyway, you can fix the issue by adding a -T tag to your commands.

image: docker

services:
  - docker:dind

before_script:
  - apk add --no-cache py-pip
  - pip install docker-compose
  - docker-compose build
  - docker-compose up -d
  - docker-compose exec -T php composer install

tests:
  script:
    - docker-compose exec -T php phpspec run --format pretty
    - docker-compose exec -T php phpunit
    - docker-compose exec -T php behat

This should do the trick. Hope it helped. Happy testing.

Update: Actually, maybe I spoke too fast…
I have an issue with the network. Containers cannot communicate with each others… Maybe I can play with the network options (network_mode?).
If a docker expert is here, I would love some help :)

Image by Paradasos (CC by/nc)

Testing your app with docker-compose on CircleCI

Yann Rabiller — Tue, 02 Oct 2018 14:20:38 +0000

This article was originally posted on my blog.

As a dev, you use docker as a dev environment. You're quite happy that you finally ended mastering it (or at least make it work \o/). Since you're a great developer, you know the importance of automated testing, and you wrote a bunch of specs or features to test. You made everything work locally thanks to a few docker-compose commands. Maybe you're thinking now that it could be awesome to even automate the process of launching those tests, by delegating this process to a CI, that will listen to your Github events, and send you back a green or red dot on your Pull Request's page.

Since you used CircleCI a few years ago, since they claim it's easy to use with docker and since they provide a free plan, you think you're gonna make it standing on your head. Well, let me tell you that it can be quite a pain in the a** if you don't have the right instructions, and the documentation is quite awful when it comes to using it with docker-compose. Fortunately, it can be very easy when you get the right options to use in the config.

Let's dive into it!

After having created your CircleCI account and connected it to your repository, you will have a sample config file given by CircleCI. It may look like this (hum...):

version: 2
jobs:
  build:
    working_directory: ~/mern-starter
    # The primary container is an instance of the first image listed. The job's commands run in this container.
    docker:
      - image: circleci/node:4.8.2-jessie
    # The secondary container is an instance of the second listed image which is run in a common network where ports exposed on the primary container are available on localhost.
      - image: mongo:3.4.4-jessie
    steps:
      - checkout
      - run:
          name: Update npm
          command: 'sudo npm install -g npm@latest'
      - restore_cache:
          key: dependency-cache-{{ checksum "package.json" }}
      - run:
          name: Install npm wee
          command: npm install
      - save_cache:
          key: dependency-cache-{{ checksum "package.json" }}
          paths:
            - node_modules
  test:
    docker:
      - image: circleci/node:4.8.2-jessie
      - image: mongo:3.4.4-jessie
    steps:
      - checkout
      - run:
          name: Test
          command: npm test
      - run:
          name: Generate code coverage
          command: './node_modules/.bin/nyc report --reporter=text-lcov'
      - store_artifacts:
          path: test-results.xml
          prefix: tests
      - store_artifacts:
          path: coverage
          prefix: coverage

workflows:
  version: 2
  build_and_test:
    jobs:
      - build
      - test:
          requires:
            - build
          filters:
            branches:
              only: master

Well, that's quite intimidating. At least there is the docker keyword, so you think you're going in the right direction. Let me tell me you're wrong.

Actually, this docker keyword means your CircleCI build will be launched in a docker container instead of a Linux VM. After reading the whole documentation, you realize that you have to use a Linux VM to be able to use docker-compose with volumes (link: https://circleci.com/docs/2.0/executor-types/ ).

So let's create a new config file, step by step.

version: 2 # CircleCI version
jobs:
  build:
    machine: true # Use a Linux VM instead of docker environment
    working_directory: ~/repo # Default working directory, where your project will be cloned

So we have a very basic install. Nice. Let's add a checkout of the repository.

  build:
    # ..
    steps:
        - checkout
        # Maybe you need to add some config file specific to circle…
        - run: cp .circleci/.some-parameter-file .some-parameter-file

Docker-compose is by default installed on the Linux VM provided by CircleCI. We can directly build and up our containers.

  build:
    # ..
    steps:
        # - …
        - run: docker-compose up -d

Now you can install the dependencies of your project. Here we have node (yarn) and PHP (composer) dependencies.

    steps:
        # - …
        - run: docker-compose exec php composer install -n --prefer-dist
        - run: docker-compose run --rm front yarn install
        - run: docker-compose run --rm front yarn build

Now we can run our tests!

        # run tests!

    steps:
        # - …
        - run: docker-compose exec php vendor/bin/phpspec run -vvv
        - run: docker-compose exec php ./vendor/bin/behat -v

Tada! An extra bonus? Let's say you do some End2End testing and you take some screenshots when a test failed… Maybe you want to be able to access the screenshot (or log file) from the CircleCI interface? You can add a directory as an artifact. This will be then available in the artifacts link above your tests.

    steps:
        # …

        # This line is to be able to access failing screenshots in the
        # artifacts section in CircleCI
        - store_artifacts:
            path: ~/repo/features/fail-screenshots

So cool! Now you have a CI running with docker-compose, using your dev environment. Pretty swag.
Now, some of you may encounter permissions problems because of the users. This can be because CircleCI uses a user with id 1001 and a group with id 1002. Sometimes in can conflict with your local permissions (your local user being 1000 in general). If so, you can specify the user that will launch the docker command.

    steps:
        # run tests!

        # Circleci uses a user with id 1001 and a group with id 1002
        # We use this user instead of the default one in our dockerfile (1000)
        # to avoid permissions issues
        - run: docker-compose exec --user=1001:1002 php vendor/bin/phpspec run -vvv

        # We use the root user here to change logs and cache permissions
        - run: docker-compose exec --user=root php chmod -R 777 var/logs
        - run: docker-compose exec --user=root php chmod -R 777 var/cache

I hope this article helped you to make this small green dot appear on your PRs :).

(Using Gitlab? See here)

Image credits: "Bricks in circle" by Alessandro Mancini

Job offers: Don't get lost along the way

Yann Rabiller — Tue, 09 Jan 2018 06:47:54 +0000

Dear potential employers,

I know your company is dealing with urgent issues. I know the market is quite rough at the moment. I know good developers have now high and diverse expectations: keeping track of these must not be easy.

It seems like for some of you, free coffee or free candies are a must have. Available Nerf guns in the office are maybe the line in your job offer that will make your company stand out from the others.

Maybe you're right. Maybe I totally underestimate this kind of features. But one thing that matters to me and that you often forget, is the technical stack you want me to deal with.

I'm not kidding. Some offers don't even mention one programming language. You could think it's an exception and that I chose only small and dubious companies. You would be wrong.

Here is a job offer to work at Reddit.

It seems all they want is clean, maintainable, and well-tested code. You should know what it means, you, little Backend developer. Does it include Node? Python? Ruby? Rust? PHP? Go? No one will know. I hope you are working to be familiar with the whole web stack.
Consider the list of all the things we know about this offer.

Pet Care Stipend
Monthly Cell Phone Allowance
Catered Meals & Snacks

It's great to know this. But I have the feeling that the authors got lost along the way. Please, next time, try not to forget to mention a few more details about the work I will be doing for you. Write it down even at the very top of your job offer. It will save time to anyone.

Lessons learned about Bus Factor (5/5): Detect it before it is too late

Yann Rabiller — Wed, 27 Sep 2017 15:08:59 +0000

This series of articles is taken from a talk I gave at the Berlin PHP Meetup and was originally posted on my blog. If you didn’t read the first one, here you go.

In the past articles we wrote about the daily strategies you can set up to share knowledge, balance the level of your team and help anyone dive into your own code. It’s obviously essential to keep this issue in your mind on a daily basis. But now, is there a way to detect the Bus Factor of your project? How do you know another member of your team or a new developer could easily take up the reins of your project?

This question is crucial, since it is the kind of issue you generally detect when it is already too late (remember my little story in the first article?). After a few fails, my colleagues and I didn’t want only to prevent these bad experiences in the future, but also to detect the projects where this could happen again.

A year ago, during a hackathon, it led to a productive discussion between all the devs of my company. We ended up with a funny idea. Here is what we do, about every two weeks or every month.

The Bus Factor Review

Take a project. Then take all the developers of your company who never worked on this project. Only them. And you choose one of them, randomly.
Their goal is to take about an hour or two, to clone your git repository, to install the project on their machine, and to understand the domain, and some implementation. They can’t have any help from another developer. They can only rely on what is written in the repository. If they find something to say (installation problems, obscure domain, strange and not documented architecture…), they open a Github issue and list the problems.

Trust me, at first, some developers cannot even install the project, because there is for example a mandatory parameter that was forgotten in the Readme. In this case, they just stop right there and write an issue. Then, two weeks later, you take another developer and he or she does the exact same thing. The idea is to detect things that are only said orally and not documented in the repository. By doing it regularly in an iterative way, it does not take a lot of time, and it can help you detect a lot of implicit things.

When you do this review, the idea is to imagine if someone wants you to add a new feature or to debug something in this project you don’t know. Would you be at ease to fix a bug or add a new feature in this project? If not, why? What is this unusual pattern you don’t understand? What are these classes that are very badly named? Are the tests explicit enough?

We all know that we tend to delay refactoring or writing documentation. “Yeah, later”. We like to imagine ourselves in the last days of the project, cleaning everything that is dirty, writing a wonderful and explicit documentation, before we leave it to the client. Oh, come on. Be honest. It never happens this way, because 1/ the last days of a project are in general stressful (because you’re close to a deadline or to the end of a budget) and 2/ because you don’t remember all the “wtf” implementations that would be obscure to a new comer. You got used to it. Testing regularly your project with a new look will force you to improve the quality of your code and documentation during the coding process. Moreover, the fact that different new people look at it will obviously help detecting various problems (every developer is not disconcerted by the exact same things).

To summarize

Do systematic code reviews
Give complex tasks also to the juniors but help them
Stay close to the domain of your client
Use high level tests reflecting your domain
Write explicit code
Detect a lack of shared knowledge as soon as possible, and write down everything in your repository/code. Stop this oral culture: act as if your private project was an open source project on which every unknown developer should be able to collaborate

That’s it! I hope this series will help you in some ways. If you agree or disagree with a statement or use other techniques to increase the Bus Factor, please let me know! All comments are highly appreciated :).

(Special thanks to Shivoham, Amandine and CÃ©cile for their ideas and proofreading)

Picture credits: "ThePollDiaries_003_BavariaFilmInternational" by Berlin Beyond.

Lessons learned about Bus Factor (4/5): Stay close to the domain

Yann Rabiller — Wed, 27 Sep 2017 15:07:04 +0000

This series of articles is taken from a talk I gave at the Berlin PHP Meetup and was originally posted on my blog. If you didn’t read the first one, here you go.

(If the gist snippets don't show up, try to refresh the page. Seems dev.to is having some issues with it)

Last time we saw how we could refactor code in a simple way to make it more obvious. We did not talk yet about your client’s domain. Maybe we should have done that in the first place.

Stay close to the domain

When you create a website for a client, you initially don’t know their job. It can be about printing, banking, shipping stuff… whatever. You’re not an expert of these fields. Even if you have knowledge in those, every company has their own vocabulary, processes and issues. Your first concern, when building a great application that is maintainable, should always be to understand the domain of your client. Not only do you have to understand it, but it’s even better if you use the exact same words they use. This is called ubiquitous language, and it’s a common concept in Behavior Driven Development and in Domain Driven Design. Using the same vocabulary as your client will avoid you wasting a lot of time translating what they are talking about. If you don’t know Ubiquitous language, you can check this nice article presenting this concept. Here are a few quotes from it, that summarize the key points, in my opinion.

You can name your classes, methods, and variables anything. Why not use the terms that your domain experts use?
[…]
[Ubiquitous language] is reflecting in code how the users of the software think and speak about their work.
[…]
Programmers should speak the language of their domain experts, not the other way around.

Sometimes you will even realize that your client has not a clear vocab for a few things. Help them then, to find the best term to describe something and to keep always this same word as THE word. When you made all this work of understanding and translating your client language, please, write it down in a glossary. It can be in a Github wiki, or maybe better, directly in markdown pages put in the doc section of your repository. Write there, all the important concepts of your client. What is a retailer? What is a customer? How is defined an invoice? What defines a license and what is it used for? If your client does not speak english, write the matching between their terms and the terms used in the app (because yes, you will write your code in english. That should be obvious).

This is a really important tool to help a new developer to understand the domain and its implementation in the code. Actually, if you write explicit code and stay as close as possible to the domain, a salesperson with no coding knowledge should be able to read your code and tell you if you’re implementing the logic in a good way. It’s not always possible I got it. But that should be your ultimate goal.

Writing tests is also writing documentation

It’s quite obvious that tests will help you improve the quality of your code and avoid bugs. Great. But tests can also be a great way to help a developer dive into your project. The first thing I check when I dive into a new project, is the presence of functional tests. That can make you understand very quickly what this application is about and what it does. And then, if I want to understand more in detail what different classes do, I can check unit tests. As a PHP developer I like to use Behat (a kind of Cucumber-like for those who are familiar with it), a simple test runner allowing you to describe scenarios in a human readable language called Gherkin. Here is how it looks like:

Every feature is a list of scenarios, describing a specific user journey. Given and When statements describe an action. Then statements decribe an expected result (what we also call an assertion). Behat (or any Cucumber-like tool) will parse these *.feature files and launch your scenarios one after another, by translating all these Given, When, Then, into concrete code you implemented. Behat will do that thanks to PHP annotations, but the other tools and language implementations are very similar.

These tools are just test runners that let you free to write very explicit and simple tests scenarios, that every human understands. This allows you to write these scenarios with your non-dev client when they ask you to do a new feature, and to help any new comer in the project to understand what the application is about. Cucumber-like tools and Gherkin are amazing to clarify your project.
The problem is that these tools allow you to do many many things, from scratch. Like manipulating a browser with already written Gherkin definitions. So usually, when looking at Behat tests, here is the kind of scenarios you could find in many projects.

Sure, it describes something. But it does not describe your domain. It describes a user journey thanks to a user interface, without really explaining the business rules.

First, since it is totally coupled to the user interface, what happens if you’re working on a foreign project? Maybe you will start to see these kinds of things:

Wuuuh. Ugly. As a french developer I can assure you it’s a quite common thing to see. But the most serious problem here, is that you lose the main topic of documentation you should care about: the domain of your client. Gherkin is a great tool, if you only describe the goal of the application in domain terms, without worrying at all about the concrete technical implementation. This scenario could be implemented with a classical website, a JSON Rest API, or a simple CLI. That is not our problem here. We want to describe where and why your mean of transportation is driving you. Not the colour of your car. Here is how we could describe our feature instead:

How is it implemented? HTTP? Shell? Whatever. We don’t care on this level. Here you can really describe the business logic of your app, and check with your client if you really understood the additional value of their project. What’s even greater, is that it allows you to test the same scenario in different ways (end-to-end test with Selenium, infrastructure tests on the application layer…): these tools allow you to tag (@ui or @integration, for example) your features and scenarios and send these features to different layers of testing.

For those who want to go further, I really advise you the article “Introducing Modelling by Example” by everzet (the creator of Behat) which explains much better and deeper what I just said (among other things). Also, if you want to know how it looks like to use Behat (or any Cucumber-like tool) the wrong way, I encourage you to read “Stop Simulating BDD, Write Tests from Codeception’s blog (Codeception is another PHP test framework). Don’t get me wrong: I’m not saying Codeception is a bad tool or that Behat is necessarily better (I never worked with Codeception). I’m just saying the given arguments show a total misconception of the tool. This article shows the worst way to use Behat, so in the end we could say it’s a great article because it’s very instructive.

Staying as close to the domain as possible, and documenting the main goals of your app in a business language will help anyone to dive into your project and understand right away why all this has been built.

In the next (and final) article, we will think about how we can detect a Bus Factor issue as quick as possible.

Image credits: "The Entire City" by Max Ernst.

Lessons learned about Bus Factor (3/5): Write explicit code

Yann Rabiller — Wed, 27 Sep 2017 15:06:04 +0000

This series of articles is taken from a talk I gave at the Berlin PHP Meetup and was originally posted on my blog. If you didn't read the first one, here you go.

Dev.to has some issues with my Gists. It scrambles them! You should definitely read this article here instead.

Write explicit code

Last time we talked about the strategies you could set up to share knowledge within your current coding team. It's great, but it would be even better to help anyone to read your code and understand your implementation right away. Let's dive into some concrete code.

Let's say you are new on a project and you have to add a new feature in this part of PHP code below. I know, it's PHP. But don't leave. It's a basic one, and even if you hate that language, it should not be a problem to understand what is going on. These considerations should apply to almost any language and code. This is a dummy example I wrote, to reflect the kind of usual bad code you can find when you join a random project.

Try to understand what this code is about, in a few seconds.

Ok, I think you got it: the previous code is about calculating shipping fees. But that was not so obvious to get, and still, it is a very simple and short class. Imagine how it can feel for a newcomer in your project if there are hundreds of classes like this, and five times as long as this one.

Let's try to clarify that.

First, the naming is very bad. Service does not mean anything and the method name is not explicit enough. We rename the namespace, the class and the method (l. 3, 5, 14):

Better. Now the next problem is that a Calculator should calculate and return a value. Here, it calculates and sets the value to an object. This is misleading, and multiplies the responsibilities of the class. It also finds the Cart object from a repository: it is quite hard to defend the injection of a repository in this simple Calculator class. Let's directly pass a Cart object as parameter (allowing an explicit typehint) and just return the calculated value (l. 9, 29).

This if/elseif is confusing and takes too much of my energy to follow. Let's get rid of that (l. 21 and 29):

I feel better already. This calculation of the total of the cart could be the responsibility of the model. Then let's get rid of it too, and add an explicit method name so that we know what total we are talking about (because yes, when calculating prices, knowing if we include VAT or not can be interesting) (l.13):

I still have an issue here. What are all these magical numbers? 20? 40? 100? If you are new to the project, chances are that you will be a bit afraid to change one of them and will ask to your client or your colleagues what they actually mean. If they are supposed to change, we inject them as parameters with clear variable names. If they are not, then we can use constants (l. 11, 17, 22, 25):

This could look a bit overkill to use constants here, but it will help for sure any new comer to the project to understand right away what is going on. Even better: if you have a question about these numbers, you can directly ask your client about the threshold for free shipping fees instead of making them guess about this 100 number that could be anything in the app. Finally **it allows you to centralize these informations somewhere and reuse them in the app, avoiding you some headaches while refactoring.

This is way better. But I still have a last issue here. I guess these numbers are some money. But with what currency are we working here? Euros? Dollars? Yen? If you clarify this right away, that will prevent every developer from being lost when the app is growing. For this, we can use the Money library which implements Martin's Fowler Money pattern. We also add a return typehint, since we can do it since PHP 7.1 (l.5, 14, 18 and 26):

If it is maybe as verbose as the initial code, I think this code is much easier to read, to understand and to maintain. You understand right away what we are talking about and what it does, without the need of any comment. This will also (in my opinion) help a lot of new comers in your project to dive into your code and be able to refactor or maintain any class. It will avoid the team to waste time with infinite questions, since the code is self-documented. This is obviously a very simple example I took for the purpose of this article, but I think this way of refactoring and writing explicit code can apply to much fatter classes. Also this Calculator is a dummy example: we could (should?) do that directly in the model instead of instantiating a service for this simple task. Once again, it was just a straightforward example to show a few common problems we can find on a daily basis.

Next time, we will talk about one of the most important issues when lacking of knowledge sharing: the domain.

Picture credits: "Juventae Chasma" by European Space Agency.

Lessons learned about Bus Factor (2/5): Balancing the level of your team

Yann Rabiller — Wed, 27 Sep 2017 15:04:41 +0000

This series of articles is taken from a talk I gave at the Berlin PHP Meetup and was originally posted on my blog.

This cute kitten has absolutely nothing to do with Bus Factor, unlike the first post of this series.

Now we’re here, let’s dive into the lessons I learned about how to share knowledge inside your current coding team.

Code Reviews

I know this one is a big classic in the industry, but I think it is always good to emphasize it as a general advice. At KNPLabs (the company I work in), we automatically do a code review for every feature or every fix. You can’t merge your own pull requests.

Why that?

First, it’s obviously a question of quality of code. Code reviews help detecting bugs and prevent bad implementations.
Second, it will teach you new ways to code, or to solve a problem and it will ensure that at least another developer has seen what is going on in this part of the application (if your application is growing fast, there is a chance you don’t keep track of important changes or implementations).
And finally, a part that seems really important to me: it helps reducing tensions within the team. If you introduced a bug in the app, you’re not the only one responsible for it. The whole team is responsible. This way you can’t tell “This guy or this girl did that”. The one who merges it is equally responsible. You will then share fails and victories together. I do trainings sometimes and I am always shocked by how the coding and merging process can influence on the global ambiance. A mandatory code review process does not ensure by itself a friendly and united team. But no process at all with no shared responsibility between developers guarantees tensions, for sure.

Code reviews are definitely a great tool. But it is not enough. Because we all know this moment when you’re tired and stressed and you have to review 2000 lines of code at 6pm. In this case you sometimes close your eyes on something you don’t understand cause you know… “f*** it, let’s merge it”. If you have fat pull requests to review, it is a good idea to ask your colleague to present you their work and to review it in pair.

Improve the level of your juniors

Let’s say you have two seniors in your team and one junior. Here is what usually happens.

You are doing your sprint planning and you have 3 features/fix requests.

Implementing a catalog import with RabbitMQ and Elasticsearch (I took that example randomly, for sure)
Synchronizing two databases
Fixing a lot of broken translations

The two first are complex ones. The final one is a simple (but quite boring) task. Right now, the junior developer is panicking cause they don’t have any clue how to handle the two complex tasks and they hope they are not asked to do these tasks. Well, actually it’s not a problem, because the two senior developers are already discussing how fun it will be to deal with these complex issues, and start talking about a new esoteric and exciting paradigm they want to try. The junior is relieved and every one is happy…

For now.

Because sooner or later, this junior developer will probably have to dive alone into this code, and spend a stressful day first trying to understand the implementation and then trying to fix it. And we’re back to my little story from the beginning. Also, if we always give the most simple tasks to our junior developers, how can we expect them to level up?

Here is a simple but smart solution.

Do not always give the most complex thing to do, to the best developer.

Regularly (not always), ask your junior developer, if they agree, to take one of the most complex tasks. The fact that they take it does not mean at all that they must be alone on this. Tell them that they can ask you any questions they want at any point, and that you can do pair programming with them to solve this problem. Make everyone comfortable, and explain to the junior that it’s obviously not a shame if they have no clue how to do this. We all start at one point, and there is no problem being lost with a new technology or paradigm.
In general the junior developer will accept the offer, with a bit of fear. They will be very happy soon to have responsibilities in this team and to finally understand this new pattern or language.

Pair programming is a great tool, because (unlike code reviews) it does not only give you the result, but also the process of thought of your colleagues. If I think about my own experience, pair programming or just discussing with a more experimented developer about a future feature were the most rewarding moments in my short career. These moments are probably the ones when we learn the most how to think and code.

Next time, we will see how to make our code more explicit to ensure that a new comer will find their way in it.

Picture credits: "_DSC2079" by allenran 917.

Lessons learned about Bus Factor (1/5): Introduction

Yann Rabiller — Wed, 27 Sep 2017 15:03:04 +0000

This series of articles is taken from a talk I gave at the Berlin PHP Meetup and was originally posted on my blog.

Let me share with you a little story of mine. About 2 years ago, I was working on a quite complex project to create a marketplace from scratch. We were two on the job, and my colleague was a much more experienced developer than I was. We finally made this app and released it. A few months after that, we had a bug in production concerning catalog importation, involving a complex system working with RabbitMQ and Elasticsearch. I had never touched that part of code. And my colleague was on holidays. I was designated to fix it. Cause you know… “you worked on this project, right?”. Sure.

The reality is that I didn’t know at the time how all this worked and I found myself completely lost and panicked to understand all this stack. In the end, I didn’t manage to fix that bug. It led to frustration, stress and loss of confidence from myself, my colleagues and my client. That was a horrible experience.

Sounds familiar to you? If so, this series of articles is for you.

Bus Factor?

You can find several slightly different definitions of the Bus Factor on the web. Let’s make a patchwork.

The bus factor is the total number of developers who would need to be incapacitated, as by getting hit by a bus, so that the project would be left for dead.

In other words, the bus factor estimates the number of developers that are vital to a project, for any reason (lack of understanding of their implementation or information withholding). If those developers are gone (on holidays, fired, or just away), no one is able to maintain the project or to add new features anymore. In technical terms, that could be considered as detecting the single point of failure within the team.

This little thought experiment can help you to detect this kind of situation before it happens. If you have a bus factor of 1 (which means that with just one developer away, your team does not feel like it can maintain the project), then you have a serious problem. The goal is to increase this bus factor to the maximum and to share knowledge so that you can prevent your project from falling apart.

In this series of articles, I will try to give you a few lessons I learned about knowledge sharing within your coding team, and also outside your coding team. Because you would like all your colleagues (even the ones working on different projects) to be able to help you at one point. Or just because it also applies for when your client decides to put their own developers on the project. You don’t want them to be stuck and to contact you every two weeks. Even if they don’t contact you, you don’t want other developers to feel the same way as I did (because you’re a good person. I know it). In the very next article I will present the essential ways of sharing knowledge inside your team. This will be followed by two other articles about strategies that apply for every developer outside your team, and finally by a bonus article about detecting as soon as possible a Bus Factor issue.

Next is available here.

Picture credits: "Bus accident on Empire Way, 1933" by Seattle Municipal Archives.

Nice to meet you, buddy.

Yann Rabiller — Wed, 15 Feb 2017 12:39:21 +0000

PHP/Symfony developer and trainer at KNPLabs. Living in Berlin right now.
You can find me on Twitter as @Einenlum