DEV Community: Luis Mirabal

Better commit messages: Structure

Luis Mirabal — Wed, 13 Aug 2025 18:08:46 +0000

In a previous article, I wrote about the importance of commit messages and what they should focus on. However, I have some more thoughts about commits. There are a handful of rules and conventions that can elevate further the quality of your commits.

Foundation

There are some basic format rules that every commit should follow:

The title should ideally have under 50 characters, but these days if you are under 72 is still ok.
The body is optional, but if there is one, you should separate it from the title with a blank line and each line should have up to 72 characters.

These guidelines allow your code to be shown properly on any git client or tool displaying commit messages.

Even though it's not about format, another basic convention you should follow is to write your title as a command. A good way to test this is to complete the sentence: If applied, this commit will "your title".

These basic rules provide your commits with a good foundation. The next step is to give context to your commits, which is where conventional commits come in.

Conventional Commits

The conventional commits specification define rules to provide context on what your commit does. So you can have commit titles like:

feat(payee): add ability to update contact details
fix: stop payee manager memory leak
chore!: update java version to 21

It allows to easily tell apart feature work, from bug fixes, refactoring, etc. This is primarily useful for automation tools, so that they can:

Release a version of the software, automatically working out which part of the semantic version to increase.
Provide release notes highlighting new features and bug fixes, and potentially hiding changes that are not relevant to consumers.

At the same time, it also gives a hint about what a commit is about to anyone looking at the git history.

Scope misconception

A common misconception is how to use the scope (word in parenthesis in the first example). Its goal is to specify what part of the codebase is affected - which can be particularly useful for large monorepos. Instead, it's sometimes used to include a reference to the ticket the commit relates to.

Avoid misusing the scope by using better conventions to provide a ticket reference, as explained next.

Ticket Reference

Most commits are about delivering work that's described in a ticket in your project management tool. Including a reference makes the commit searchable and provides additional context to the reader.

However, it's not the main piece of information you're looking for in a commit message, yet it tends to be added to the title taking vital characters that can be used to explain the actual change.

I'm in favour of including the ticket reference, just not in the title. I suggest you should mention it at the bottom of the text. You can simply add the reference or use a commit trailer format, like:

Fixes: ABC-123
Relates-to: ABC-123

Some tools would close tickets if you use the correct format, so look out for it if you're interested in automating ticket status updates.

No reference

There will always be cases where there's no ticket to refer to, so in that case you can simply omit the footer. Still, if you want to automate the validation of your message format, you need to come up with a convention for this case. The following are good alternatives:

Relates-to: N/A
No-ticket: reason for not having one
Require ticket reference only for feature work and bug fixes.

Setting a convention on how to refer to tickets is very important to bring consistency to this topic. Giving credit to everyone who worked on the change is just as important.

Co-authoring

If you do pairing/mobbing in your team, a best practice is to ensure proper attribution by including your co-authors.

As this is a common use case, there's convention to add it as a footer using a commit trailer, like:
Co-authored-by: Luis Mirabal <luis.mirabal@mail.com>

This is supported by many tools so all authors get shown where commit details are displayed.

Besides crediting authors, another useful piece of metadata you can add to a commit are links to external resources. This was a personal source of frustration, as they can be tricky to handle when long and in the middle of the message. In the following section I will provide you with a strategy to manage them.

Links

Long URLs are a common exception to the line length rule, as a working URL is more important than line length. However, placing long URLs directly in the body of a commit message can disrupt the natural flow of the text, making it harder to read.

An approach that solves this problem is to use reference-style links, which keep the main body of the message focused on the text while moving the long URLs to a reference at the bottom. This makes your links look like the following:

See [payee management documentation][1] for complete API reference.

[1]: https://docs.verylongexampledomainname.com/api/payees#update-contact-details

This way, the URL is at the end of the text, and doesn't get in the way of your message. This is rendered nicely if the client supports markdown, yet it's still easy to understand as plain text.

Putting It All Together

Perhaps the most convincing argument for adopting these conventions is to see what a beautiful and informative commit looks like when they are all applied:

feat(payee): add ability to update contact details

Allow users to modify email, phone, and address information for existing
payees through the edit payee form. Added validation for email format
and phone number patterns.

See [payee management documentation][1] for complete API reference.

[1]: https://docs.verylongexampledomainname.com/api/payees#update-contact-details

Fixes: ABC-123

Co-authored-by: Luis Mirabal <luis.mirabal@mail.com>

Following these simple rules, you create well structured commits that are rich in context. Context will make your commits easier to understand for future readers. While structure makes them searchable and enables a number of automation avenues that wouldn't be possible otherwise.

Thoughts on why writing good commit messages is a good investment

Luis Mirabal — Wed, 25 Jun 2025 19:23:43 +0000

Luis Mirabal

Jun 25 '25

Better Commit Messages: A Long-Term Investment

#softwareengineering #cleancode #git #productivity

Comments

3 min read

Better Commit Messages: A Long-Term Investment

Luis Mirabal — Wed, 25 Jun 2025 19:20:32 +0000

Spending time writing commit messages is an area of software development that's often overlooked. I used to do it myself—paid no attention to my commit messages and focused solely on the code. Although the code remains the most important part, paying attention to your commit messages will pay off.

Why it matters?

My perspective on the topic changed after facing difficulties understanding code written years ago, sometimes even code I wrote. When you work on a project that has been running for several of years, you often find yourself trying to change code that no one remembers the reasoning behind it. You end up on your own trying to figure it out or, in extreme circumstances, you end up circumventing it to reduce the risk of breaking production.
After being stuck too many times, I learned to care about my commit messages. However, once I made it a habit, I realised there were a number of additional benefits:

Writing forces a deeper understanding of the changes. You understand the solution in your head, but there tend to be gaps in your thoughts that become clear when you explain it. You'll be surprised how many times you can find flaws in your solution. In my experience, this has been the greatest benefit.
It can help you break down commits. If you start writing your reasoning behind the solution, and end up with a very long message touching on multiple topics, it's often a symptom your changes are doing too much and could benefit from splitting into multiple commits.
It helps your code reviewers by providing context upfront. They can start by reading your reasoning before diving into the diff, likely answering many questions they would've had if they looked at the diff alone.
It speeds up your team in the long term. You might think that spending time on this will slow you down—and it will on a given commit. However, it should lead to better solutions, smaller commits, likely fewer bugs and ultimately save time the next time the code needs to change.

Capture the why

I hope you find the argument as compelling as I do. The next step is to work out what you should include in the message to make it useful. And as I alluded to in the benefits, the key piece of information is the thinking behind your solution—the why.
Providing details of the thought process that made you pick that solution should be the goal of the message. Unfortunately, it's more difficult than it sounds. It's much easier to explain what the change does as it's explicit in the code, so that's what we naturally tend to do.
The why is in the thoughts you had when:

You were coming up with the solution
You realised it wasn't the right one and went for an alternative
You discussed it with colleagues
You found advice on the internet

All of this information seems obvious to you when the changes are ready to commit. You're done with all the thinking and already want to move on to the next thing. But this is the moment when you need to pause and record all this useful information.

Writing tips

The last point to master the skill is to think about how to write your message. This is something I still struggle with, and I thought to mention a few tips:

Try to be concise. Keep the what in the title and focus the body on the why. It'll help you land the message.
Think of your audience. If you're making changes in an area where the maintainers are not experts but depend on it, take the time to educate them.
1-liners might still require an explanation. The amount of code is not the determining factor, but rather the amount of thinking required to make the change.

I'm a strong advocate for investing time to provide quality in the work you produce. That covers the whole software development cycle, which starts to materialise in your commits. Writing great commit messages can be tedious at times—but it's a habit that pays off. It improves your thinking, helps your team, and strengthens your codebase. The next time you're about to commit, take a moment. Invest in the why.

Hexagonal Architecture Testing

Luis Mirabal — Sun, 24 Jan 2021 18:26:28 +0000

The hexagonal architecture, also known as the ports and adapters pattern, helps us isolate an application business logic from any technology-specific code. It affords you extra flexibility. You can either defer decisions on what technology to use or migrate to a better alternative that might appear in the future.

If you're not familiar with it, the main principle is that your business logic, the hexagon, is protected and can only communicate with the outside world via interfaces, the ports, that are then implemented in your technology of choice, the adapters.

There are two types of ports:

Driving port: contract defining how the application is triggered.
Driven port: contract defining how the application communicates with the outside.

If you need more details, please read Alistair's Cockburn post or watch his presentation.

Testing

We've already touched on the main driver for implementing a hexagonal architecture, but it doesn't stop there. It also has a beautiful side-effect. It allows testing all your application functionality in business terms, removing added complexity from libraries and frameworks, as they're isolated outside the hexagon in adapters behind port interfaces.

Even though the adapters don't have any business logic, they play a vital role. They bring the application to life, allowing users to consume it. Without them, the user couldn't input any data or store it, just to mention every application's essential requirement. Therefore, making sure they work as expected is of the utmost importance.

Unfortunately, this tends to end up causing test duplication and blurring their focus with technology-specific details. For example, if you were building a web application with an HTTP backend, you'd have a test making sure the UI can take the details and store them properly and another testing the same in the HTTP API and even a third in the domain logic.

At this point, the hexagonal architecture shines. You can build a functional test suite interfacing with the application via driving ports. With a major benefit, they don't need to include any component-specific implementation details, which allows you to re-use the same test suite at every level of the application by implementing the given contract.

It all sounds great on paper but let's build an example from scratch to see the benefits in action.

Building a bank

To bring the theory to practice, we're going to build a basic bank. The requirements are as follows:

Can create accounts.
Can list accounts.
Can deposit money to an account.
Can withdraw money from an account.
Forbids withdrawals when there are not enough funds.

As a backend developer, I'm using a JVM language; kotlin. To build the HTTP API, and even a rudimentary Web UI, will use http4k. Hopefully, even if you're not familiar with either, the code is still going to be easy to read and understand.

Create account

Let's start implementing the first requirement by writing our first test.

abstract class BankContract {
    abstract val bank: Bank

    @Test
    fun `lists accounts`() {
        val account1 = bank.createAccount()
        val account2 = bank.createAccount()

        val accounts = bank.listAccounts()

        assertThat(accounts, equalTo(listOf(account1, account2)))
    }
}

interface Bank {
    fun createAccount(): BankAccount
    fun listAccounts(): List<BankAccount>
}

This is a special kind of test, as it represents the application contract alongside the Bank interface. Typically, the interface is considered enough to enforce a contract, but it leaves out an application's fundamental element, its behaviour. If you have a test written in terms of the interface, you end up with an even stronger contract as the types and the behaviour are well defined.

For this reason, it makes sense this test is abstract as it's the template that implementations need to follow to comply with the bank behaviour.

Regarding the test itself, you can notice we're testing account listing. It's because we need to check the bank behaviour solely via its interface. Therefore, it makes sense to implement the operation that saves accounts and query them to check both are correct.

First Bank implementation

We're going to start from the application inner part, also known as the hexagon, so the domain is well understood from the beginning.

class BankLogicTest : BankContract() {
    val idFactory = RandomBankAccountIdFactory()
    val repository = InMemoryBankAccountRepository()
    override val bank = BankLogic(repository, idFactory)
}

class BankLogic(
    private val repository: BankAccountRepository,
    private val idFactory: () -> BankAccountId
) : Bank {
    override fun createAccount(): BankAccount =
        BankAccount(idFactory(), Amount.ZERO)
            .also { newAccount -> repository.add(newAccount) }

    override fun listAccounts(): List<BankAccount> = 
        repository.list()
}

interface BankAccountRepository {
    fun add(account: BankAccount)
    fun list(): List<BankAccount>
}

also function: gives access to the caller object to apply side-effects, returning the unchanged object.

The first component to fulfil the contract is the business logic itself. It's the core of our application, the component making the ultimate decision on the bank's behaviour.

Creating accounts requires instantiating account objects with a unique id and getting them persisted. Persistence is an external concern; consequently, we introduce a driven port with the BankAccountRepository interface.

For brevity, the BankLogic dependencies are not included. If you want to check out the full solution, the GitHub repository link is at the end.

HTTP API

Now that the core of the application is ready, let's expose it via HTTP.

class BankHttpTest : BankContract() {
    override val bank = BankHttpClient(bankHttp())
}

class BankHttpClient(val http: HttpHandler) : Bank {
    override fun createAccount(): BankAccount {
        val response = http(Request(POST, BANK_ACCOUNTS_URL))
        return bankAccountLens(response)
    }

    override fun listAccounts(): List<BankAccount> {
        val response = http(Request(GET, BANK_ACCOUNTS_URL))
        return bankAccountListLens(response)
    }
}

Testing the contract needs a new implementation of Bank. In this case, it's a client to interact with the API.

Usually, tests for an HTTP application will directly use an HTTP client. In this case, the BankHttpClient hides these details.

This client provides another valuable benefit. Our API users can also use it, avoiding to learn details of our HTTP implementation (i.e. paths, HTTP methods, body format, etc.), and use domain types instead.

The implementation uses the aforementioned http4k library, particularly lenses which provide a type-safe mechanism to map an HTTP response to types and vice-versa.

Having a failing test, now we can implement the server code.

const val BANK_ACCOUNTS_URL = "/bank/accounts"
val accountLens = Body.auto<BankAccount>().toLens()
val accountListLens = Body.auto<List<BankAccount>>().toLens()

fun bankHttp(bank: Bank): HttpHandler {
    return routes(
        BANK_ACCOUNTS_URL bind routes(
            POST to { Response(OK).with(accountLens of bank.createAccount()) },
            GET to { Response(OK).with(accountListLens of bank.listAccounts()) }
        )
    )
}

The server defines routes for the GET and POST methods on the /bank/accounts path, where their handlers call the Bank and map their result to HTTP responses.

This particular implementation of the test runs the application in memory, making it run fast even if testing the HTTP interface. However, nothing is stopping us from running it against a running HTTP server.

class BankHttpIntegrationTest : BankContract() {
    val server = bankHttp().asServer(SunHttp())
    override val bank = BankHttpClient(
        SetBaseUriFrom(
            Uri.of("http://localhost:${server.port()}")
        ).then(JavaHttpClient())
    )

    @BeforeEach
    fun setUp() {
        server.start()
    }

    @AfterEach
    fun tearDown() {
        server.stop()
    }
}

The test runs its own HTTP server, but we could go further and run the test against a deployed environment.

Web UI

The testing approach used so far can also be applied to test our front-end.

class BankWebTest : BankContract() {
    val httpServer: HttpHandler = bankHttp()
    val httpClient: Bank = BankHttpClient(httpServer)
    val web: HttpHandler = bankWeb(httpClient)
    override val bank: Bank = BankWebDriver(web)
}

You can see the pattern carries on. In this instance, a selenium-backed driver plays the role of client and is used to navigate to a particular URL, press some buttons and check that the HTML content is as expected. As we have access to the whole codebase in a single repo, it instantiates all the components, running the entire application in memory.

Implementing the web driver can be slightly trickier, and inevitably, it's coupled to the HTML structure.

class BankWebDriver(web: HttpHandler) : Bank {
    val driver = Http4kWebDriver(web)

    override fun createAccount(): BankAccount {
        driver.navigate().to("/")
        driver.getElement(By.id("create-account")).submit()

        return driver.getBankAccounts().last()
    }

    override fun listAccounts(): List<BankAccount> {
        return driver.getBankAccounts()
    }

    private fun SearchContext.getBankAccounts(): List<BankAccount> {
        return getTableRows().map { row -> row.toBankAccount() }
    }

    private fun WebElement.toBankAccount(): BankAccount {
        fun WebElement.getBankAccountId(): BankAccountId { ... }
        fun WebElement.getBalance(): Amount { ... }

        return BankAccount(getBankAccountId(), getBalance())
    }
}

The driver uses selenium via an http4k wrapper, that makes the code more kotlin-friendly. Also, it uses extension functions to make the code read better.

As a backend developer, I did not attempt to build a proper UI. Instead, I opted for a server-side application using handlebars templates to produce HTML.

Implementation is not included to avoid distraction with a solution that doesn't represent a proper front-end and looks very similar to the HTTP API.

To help make sense of the driver code, this is the HTML template source.

<div>
    <h2>Create Account</h2>
    <form method="POST" action="/">
        <input type="submit" id="create-account" value="Create">
    </form>
    <h2>Bank Accounts</h2>
    <table>
        <thead>
        <tr>
            <th>ID</th>
            <th>Balance</th>
        </tr>
        </thead>
        <tbody>
        {{#accounts}}
            <tr>
                <td>{{id}}</td>
                <td>{{balance}}</td>
            </tr>
        {{/accounts}}
        </tbody>
    </table>
</div>

This completes the full cycle, and now we have a working application fulfilling the initial requirements 🎉

Bank account deposits and withdrawals

What's a bank if you can't manage your account funds, so let's add tests to the contract.

abstract class BankContract {
    abstract val bank: Bank

    @Test
    fun `deposits into account`() {
        val bankAccount = bank.createAccount()

        bank.deposit(bankAccount.id, Amount(100))
        val updatedAccount = bank.deposit(bankAccount.id, Amount(200))

        assertThat(updatedAccount.balance, equalTo(Amount(300)))
    }

    @Test
    fun `withdraws from account`() {
        val bankAccount = bank.createAccount()

        bank.deposit(bankAccount.id, Amount(300))
        val updatedAccount = bank.withdraw(bankAccount.id, Amount(200))

        assertThat(updatedAccount.balance, equalTo(Amount(100)))
    }
}

interface Bank {
    fun deposit(id: BankAccountId, amount: Amount): BankAccount
    fun withdraw(id: BankAccountId, amount: Amount): BankAccount
}

The bank is taking shape, and it can now operate on account balances. As the initial section, the contract additions drive the changes needed to the whole application.

The implementation is omitted, as the next section builds an iteration on the withdrawal functionality, and deposits work similarly.

Bank account balance validation

So far, we've been only handling happy path use cases, in part to keep things simple. Now, let's implement an error case to see the approach still stands.

abstract class BankContract {
    abstract val bank: Bank

    @Test
    fun `cannot withdraw from account more than balance`() {
        val bankAccount = bank.createAccount()

        bank.deposit(bankAccount.id, Amount(300))
        val updatedAccount: Result<BankAccount, NotEnoughFunds> = bank.withdraw(bankAccount.id, Amount(500))

        assertThat(
            updatedAccount.failureOrNull(),
            present(equalTo(NotEnoughFunds(bankAccount.id, Amount(300), Amount(200))))
        )
    }
}

interface Bank {
    fun withdraw(id: BankAccountId, amount: Amount): Result<BankAccount, NotEnoughFunds>
}

data class NotEnoughFunds(
    val id: BankAccountId,
    val balance: Amount,
    val additionalFundsRequired: Amount
)

Having a strongly-typed contract is a must, particularly for error cases. That pre-requisite excludes exceptions immediately, as kotlin only has unchecked exceptions and they wouldn't be part of the Bank interface. Consequently, the natural option is to use a result type. They elegantly allow us to express the possible error when withdrawing funds.

So far, the BankAccount type has been used, but its implementation hasn't featured as it was only holding data. It now also includes behaviour, being the bulk of the changes needed to satisfy this requirement.

data class BankAccount(val id: BankAccountId, val balance: Amount) {
    fun withdraw(amount: Amount): Result<BankAccount, NotEnoughFunds> {
        return if (amount <= balance) Success(copy(balance = balance - amount))
        else Failure(NotEnoughFunds(id, balance, additionalFundsRequired = amount - balance))
    }
}

And we subsequently use it in the logic.

class BankLogic(...) : Bank {

    override fun withdraw(id: BankAccountId, amount: Amount): Result<BankAccount, NotEnoughFunds> {
        val account = repository.get(id)
        return account.withdraw(amount)
            .peek { updatedAccount -> repository.update(updatedAccount) }
    }
}

result peek function: gives access to value if the operation succeeds.

It only needs to delegate to the account object and ensure that the result gets persisted if successful. And with this, we have the core changes completed.

Now, we update the HTTP adapter.

class BankHttpClient(val http: HttpHandler) : Bank {

    override fun withdraw(id: BankAccountId, amount: Amount): Result<BankAccount, NotEnoughFunds> {
        val response = http(
            Request(POST, BANK_ACCOUNTS_BASE_URL + BANK_ACCOUNT_WITHDRAWAL_PATH)
                .with(accountIdLens of id, amountLens of amount)
        )
        return when (response.status) {
            Status.OK -> Success(bankAccountLens(response))
            Status.BAD_REQUEST -> Failure(notEnoughFundsLens(response))
            else -> throw Exception("Not expected: $response")
        }
    }
}

The client sets the expectation to signal the failure using an error status code. Not having enough funds is a recoverable client error (e.g. the user can decide to withdraw fewer funds); therefore, 400 Bad Request is the preferred choice.

As we need to fulfil the contract, the error response body needs to contain the JSON representation of the NotEnoughFunds type, the domain failure. It doesn't allow mapping the error into a message, as some might have attempted. Ultimately, giving more flexibility to the consumer interfacing with the user, as it has access to all the failure details and can decide how to communicate the operation's outcome best.

To get the test passing, we implement the server-side.

fun bankHttp(bank: Bank): HttpHandler {
    return routes(
        BANK_ACCOUNTS_BASE_URL bind routes(
            BANK_ACCOUNT_WITHDRAWAL_PATH bind POST to { request ->
                val accountId: BankAccountId = accountIdLens(request)
                val amount: Amount = amountLens(request)

                bank.withdraw(accountId, amount)
                    .map { updatedAccount -> Response(OK).with(bankAccountLens of updatedAccount) }
                    .recover { failure -> Response(BAD_REQUEST).with(notEnoughFundsLens of failure) }
            }
        )
    )
}

result recover function: allows converting a failure value into a successful one.

Using lenses, we extract the withdrawal details from the HTTP request in a type-safe manner, call the Bank, and finally, map the domain type to HTTP terms.

With these changes completed, the HTTP tests are passing ✅

And to finish the exercise, we update the web adapter.

class BankWebDriver(web: HttpHandler) : Bank {
    val driver = Http4kWebDriver(web)

    override fun withdraw(id: BankAccountId, amount: Amount): Result<BankAccount, NotEnoughFunds> {
        val row = driver.getTableRows().first { row -> row.getBankAccountId() == id }
        val form = row.getElement(By.id("withdraw-form"))
        form.getElement(By.id("amount")).sendKeys(amount.format())
        form.getElement(By.id("withdraw")).submit()

        return if (driver.findElement(By.id("failure")) == null) {
            Success(driver.getBankAccounts().first { account -> account.id == id })
        } else {
            val balance = driver.getElement(By.id("balance")).getAttribute("content")
            val additionalFundsRequired = driver.getElement(By.id("additionalFundsRequired")).getAttribute("content")
            Failure(NotEnoughFunds(id, balance.toAmount(), additionalFundsRequired.toAmount()))
        }
    }
}

A withdrawal in the UI works in 2 phases. First, we find the account in the list, input the amount, and press the withdraw button. Then, if the operation is successful, the list gets refreshed. Otherwise, it shows an error page.

The NotEnoughFunds failure value needs to be extracted from the HTML to get a compliant adapter. There are a couple of alternatives to achieve it: parse the error message to get the failure properties - or, read the details from meta tags in the HTML. The former means the HTML is not altered, but it only works if the message includes all the properties. The latter needs some tweaking in the HTML but makes it easier to test, so we went for that.

<html>
<head>
    <meta id="failure"/>
    <meta id="balance" content="{{balance}}"/>
    <meta id="additionalFundsRequired" content="{{additionalFundsRequired}}"/>
</head>
<body>
<div>
    <h2>Bank account with id {{id}} does not have enough funds</h2>
    <p>Current balance: {{balance}}</p>
    <p>Additional funds required: {{additionalFundsRequired}}</p>
</div>
</body>
</html>

Having a working withdrawal gets all the requirements fulfilled 🍾

Conclusion

With this example we've managed to build an application taking advantage of hexagonal architecture principles to get the testing centralised in a single test suite that exercises our whole application, allowing quick feedback via in-memory tests and providing integration coverage if ran against deployed services.

These are simple but powerful object-oriented design principles that can considerably improve how you structure your code and test your software.

For more details, you can find the full source code on GitHub.

Cover Photo by Priscilla Flores on Unsplash