Scala | Software Development
Scala returning to its origins: A tale of 4 chapters 
David A. Gil Méndez 09 Apr, 2025
Share 
Have you ever onboard new members into your Scala code base?
Scalable Onboarding: Easing New Members into a Scala Codebase Piotr Zawiła-Niedźwiecki
In this talk, Piotr Zawiła-Niedźwiecki, a senior AI engineer, shares insights from his experience onboarding over ten university graduates, focusing on the challenges and strategies to make the transition smoother. I will also add my own views as we go along.
The talk can be summarized around six main ideas:
- Understanding the perspective of a junior developer
- Consistency in coding practices
- Project categorization
- Code enhancements
- Readability and maintainability
- Continuous learning
Understanding the Newcomer’s Perspective
New graduates often bring enthusiasm to their roles but usually lack practical experience with enterprise-level technologies. This can lead to feelings of being overwhelmed, especially when confronted with complex project architectures. It’s essential to create a supportive onboarding environment that introduces them step-by-step to the codebase and accompanying tools.
This is true no matter how someone enters the world of coding. Real-world projects can feel intimidating. There are many tools to learn — cloud systems, CI/CD pipelines, Docker, Git, and so on. Add to that the fact that the code they encounter may look nothing like what they studied, and it can take weeks, even months, for them to feel confident and productive.
What’s the challenge here? While much of the tooling can be easily learned online, the real difficulty lies in understanding the coding style, architectural decisions, business logic, tests, and libraries used in the project. These concepts are rarely well-documented. Does the term Architecture Decision Records (ADRs) sound familiar?
To understand what a junior developer might feel diving into Scala, I recommend watching Monica McGuigan’s talk about her first year working with Scala.
Consistency is Key
Piotr stresses the importance of maintaining consistency in coding practices and project structure across an organization. Consistency benefits not only new team members but also experienced developers switching to new projects. Standardized practices allow newcomers to quickly apply what they’ve learned in one project to another, making onboarding smoother and reducing the mental effort of adapting to different coding styles.
I completely agree. Consistency — balanced with some flexibility — is crucial. There are different levels of consistency to aim for, and while Piotr touches on them briefly, I see some overlap with ideas I discussed in my talks on the Diamond Architecture, presented in Madrid and Warsaw. One tool I mentioned in those talks that helps maintain consistency across time and projects is ArchUnit.
Project-Level Strategies
Piotr recommends using a “stepping project” approach, which introduces new developers to simpler tasks before gradually increasing complexity. For example, starting with basic ETL jobs lets new hires apply what they’ve studied while building confidence. This step-by-step strategy makes onboarding less overwhelming and helps develop a foundation for tackling more complex systems.
What’s the downside of this strategy, especially for back-end Scala projects? The issue is that most projects, whether small or large, are heavily reliant on frameworks like ZIO or Cats-Effect with tagless-final encoding. Compared to vanilla Scala taught in beginner-friendly courses, these projects have a very different, Haskell-like feel.
Thankfully, things are slowly improving. With the introduction of Scala 3 and Scala-CLI, even complex concepts are becoming more accessible. For example, running your code without a build tool or understanding tagless-final encoding has become simpler. For a beginner-friendly explanation, check out Noel Welsh’s talk, Tagless Final for Humans. There’s reason to be optimistic!
Code-Level Enhancements
One of the most important points Piotr emphasizes is the need for clear and well-documented configuration files. It’s critical to avoid using default values, as these can easily confuse new developers. By adopting explicit configurations and following a domain-driven design approach, teams empower newcomers to focus on the business logic rather than being sidetracked by technical complexity.
This ties in perfectly with the principle of “explicit over implicit.” The contextual abstractions were overused to the point where even experienced engineers struggled to understand some codebases packed with implicits. Scala 3 addresses many of these issues by revising and simplifying contextual abstractions.
Emphasizing Readability and Maintainability
Piotr highlights that code readability and maintainability should always take precedence over performance, especially when onboarding new developers. Writing clear and expressive code allows newcomers to understand and contribute more effectively. Additionally, implementing verbose error types and grouping errors by domain improves comprehension by offering contextual and practical information for debugging.
I couldn’t agree more — readable and maintainable code is invaluable.
Cultivating Continuous Learning
Piotr also champions the idea of continuous learning within teams. He suggests offering resources like courses and algorithm-driven challenges such as Advent of Code. These tools encourage developers to practice in a low-pressure environment, fostering both learning and collaboration.
My Perspective on Onboarding
By combining Piotr’s strategies with some of my own suggestions, teams can significantly improve the onboarding experience for new hires. Ultimately, this will lead to increased productivity, better retention, and happier developers within the Scala community.
