Preface

If you have picked up this book, you care about the architecture of the software you’re building. You want your software to not only fulfill the customer’s explicit requirements but also the hidden requirement of maintainability, and your own requirements concerning structure and aesthetics.

It’s hard to fulfill these requirements because software projects (or projects in general, for that matter) usually don’t go as planned. Managers draw deadlines all around the project team1, external partners build their APIs differently from what they had promised, and the software products we depend on don’t work as expected.

1 The word “deadline” presumably originates from the 19th century and described a line drawn around a prison or a camp of prisoners. A prisoner that crossed that line was shot. Think about this definition the next time someone “draws a deadline” around you... it will certainly open up new perspectives. See https://www.merriam-webster.com/words-at-play/your-deadline-wont-kill-you.

And then there is our own software architecture. It was so nice in the beginning. Everything was clear and beautiful. Then the deadlines pressed us into taking shortcuts. Now, the shortcuts are all that’s left of the architecture, and it takes longer and longer to deliver new features.

Our shortcut-driven architecture makes it hard to react to an API that had to be changed because an external partner screwed up. It seems easier to just send our project manager into battle with that partner to tell them to deliver the API we had agreed upon.

Now, we have given up all control over the situation. In all likelihood, one of the following things will happen:

• The project manager is not strong enough to win the battle against the external partner
• The external partner finds a loophole in the API specs, proving them right
• The external partner needs another <enter number here> months to fix the API

All of this leads to the same result – we have to change our code quickly because the deadline is looming.

We add another shortcut.

Instead of letting external factors govern the state of our software architecture, this book takes the stance of taking control ourselves. We gain this control by creating an architecture that makes the software soft, as in “flexible,” “extensible,” and “adaptable.” Such an architecture will make it easy to react to external factors and take a lot of pressure off our backs.

The goal of this book

I wrote this book because I was disappointed with the practicality of the resources available on domain-centric architecture styles, such as Robert C. Martin’s Clean Architecture and Alistair Cockburn’s Hexagonal Architecture.

Many books and online resources explain valuable concepts but not how we can actually implement them.

That’s probably because there is more than one way to implement any architecture style.

With this book, I am trying to fill this void by providing a hands-on-code discussion about creating a web application in the Hexagonal Architecture or “Ports and Adapters” style. In order to live up to that goal, the code examples and concepts discussed in this book provide my interpretation of how to implement a Hexagonal Architecture. There are certainly other interpretations out there, and I do not claim that mine is authoritative.

I certainly hope, however, that you will get some inspiration from the concepts in this book so that you can create your own interpretation of Hexagonal/Clean Architecture.

Who this book is for

This book is aimed at software developers of all experience levels involved in creating web applications. As a junior developer, you’ll learn about how to design software components and complete applications in a clean and maintainable manner. You will also learn some arguments for when to apply a certain technique. You should, however, have participated in building a web application in the past to get the most out of this book. If you’re an experienced developer, you’ll enjoy comparing the concepts from the book with your own way of doing things and, hopefully, incorporating bits and pieces into your own software development style. The code examples in this book are in Java and Kotlin, but all discussions are equally applicable to other object-oriented programming languages. If you’re not a Java programmer but can read object-oriented code in other languages, you’ll be fine. In the few places where we need some Java or framework specifics, I will explain them.

The example application

To have a recurrent theme throughout the book, most of the code examples show code from an example web application for transferring money online. We’ll call it “BuckPal.”2

2 BuckPal: a quick online search has revealed that a company named PayPal has stolen my idea and even copied part of the name. Joking aside: try to find a name similar to “PayPal” that is not the name of an existing company. It’s hilarious!

The BuckPal application allows a user to register an account, transfer money between accounts, and view the activities (deposits and withdrawals) on the account.

I’m not a finance specialist by any means, so please don’t judge the example code based on legal or functional correctness. Rather, judge it on structure and maintainability.

The curse of example applications for software engineering books and online resources is that they’re too simple to highlight the real-world problems we struggle with every day. On the other hand, an example application must stay simple enough to effectively convey the discussed concepts.

I hope to have found a balance between “too simple” and “too complex” as we discuss the use cases of the BuckPal application throughout this book.

The code of the example application can be found on GitHub.3

3 The BuckPal GitHub repository: https://github.com/thombergs/buckpal.

Download the color images

We also provide a PDF file that has color images of the screenshots and diagrams used in this book. Check the notes at the end of the book.4

4 PDF with color images used in this book: https://packt.link/eBKMn.

Get in touch

If you have anything to say about this book, I’d love to hear it! Get in touch with me directly via email to [e-mail] or on Twitter via @TomHombergs.

General feedback: If you have questions about any aspect of this book, email us at [e-mail] and mention the book title in the subject of your message.

Errata: Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you have found a mistake in this book, we would be grateful if you would report this to us. Please visit www.packtpub.com/support/errata and fill in the form.

Piracy: If you come across any illegal copies of our works in any form on the internet, we would be grateful if you would provide us with the location address or website name. Please contact us at [e-mail] with a link to the material.

If you are interested in becoming an author: If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, please visit authors.packtpub.com.

Share your thoughts

Once you’ve read Get Your Hands Dirty on Clean Architecture–Second Edition, we’d love to hear your thoughts! Please click here to go straight to the Amazon review page for this book and share your feedback.

Your review is important to us and the tech community and will help us make sure we’re delivering excellent quality content.

Download a free PDF copy of this book

Thanks for purchasing this book!

Do you like to read on the go but are unable to carry your print books everywhere?

Is your eBook purchase not compatible with the device of your choice?

Don’t worry, now with every Packt book you get a DRM-free PDF version of that book at no cost.

Read anywhere, any place, on any device. Search, copy, and paste code from your favorite technical books directly into your application.

The perks don’t stop there, you can get exclusive access to discounts, newsletters, and great free content in your inbox daily

Follow these simple steps to get the benefits:

1. Scan the QR code or visit the link below

https://packt.link/free-ebook/9781805128373

2. Submit your proof of purchase

3. That’s it! We’ll send your free PDF and other benefits to your email directly