2

I've been taking a course on plain language writing, in order to make my commit messages more readable and understandable.

One of the main ideas in plain language writing is that your first identify who your audience is; how do you do this, and what are the usual potential audiences reading commit messages?

Improve this question
9
  • Well who did you go on the course to make your commit messages more readable and understandable for?
    – jonrsharpe
    Aug 12, 2020 at 20:28
  • @jonrsharpe Myself; but that’s not really an audience.
    – leeand00
    Aug 12, 2020 at 21:16
  • 3
    Then why did you bother going on the course? You are absolutely an audience for your commit messages, maybe the most likely one - looking back months from now wondering "why did I do that, again?"
    – jonrsharpe
    Aug 12, 2020 at 21:17
  • @jonrsharpe Well sure, but it’s not just for me. If I’m the writer, so should be writing for my audience.
    – leeand00
    Aug 12, 2020 at 21:22
  • 2
    Your future self might as well be a totally other developers. Unless you're a genius, most people won't be able to remember what exactly or why they did something 6 months down the road.
    – Lie Ryan
    Aug 13, 2020 at 9:07

2 Answers 2

Reset to default
5

There can be several potential readers with different expectations:

  1. A reviewer going over your code will read the commit message for context and to understand the rationale for the new code.
  2. Your team (and that includes you) using blame or similar tools to understand when and why was a particular change introduced into the code base, either when investigating a bug or when refactoring or changing functionality.
  3. Commit messages are often aggregated to form release notes for a particular build or version. For internal products (say, a component of a cloud service), these release notes might be directly derived from the commit messages. For products delivered directly to a customer, the commit messages might form the raw input from which the product team builds the "formal" release notes.
  4. These commit messages might be read by a release manager to assess the riskiness or relevance of a release - for instance, to know if the given commits comprising a release mean that feature P, that was promised to a customer, is now ready for beta testing at a customer site. T
  5. The commit messages aggregated for a given release might be read by devops to determine which change in a release might have caused an error or degradation in production.
Improve this answer
4
  • 1
    in my experience using commit messages for release notes tends not to work, with the possible exception of if your end users are developers
    – jk.
    Aug 13, 2020 at 7:37
  • @jk. they often are when your product is a backend service, and the devops/SRE engineers need to manage (micro)services developed by different teams with their own release schedules
    – Avner Shahar-Kashtan
    Aug 13, 2020 at 8:23
  • Clients start complaining about perf/availability of product since midnight. SRE check logs to see which services/components were updated right before, and check the release notes to see if the release might be related.
    – Avner Shahar-Kashtan
    Aug 13, 2020 at 8:25
  • 2
    @AvnerShahar-Kashtan For an internal product with internal audience, it's worth a try. For public release notes for a public product, I fully agree with jk: This won't work on the long run, because public release notes are an official communication, that has to be cleaned from jargon, and sometimes rewritten for a better readability. But maybe you could add the communication/documentation team/product management team as audience, since it could take the commit messages as input for producing the official release note ?
    – Christophe
    Aug 13, 2020 at 11:25
8

Good commit messages are underrated, in my opinion, kudos to you for trying to improve in this aspect.

I think the primary audience for commit messages are other developers. There might be other stakeholders, but they also need to be quite tech-savvy to look into commit messages anyway.

With that said, you should probably start by defining a commit message convention for your team. Having a uniform style goes a long way in making it easy to understand which changes the commit contains.

Try to look into guides like this https://www.freecodecamp.org/news/writing-good-commit-messages-a-practical-guide/

Improve this answer
5
  • 6
    Another important audience is oneself (the developer doing the commit). I mean, your future self.
    – Tulains Córdova
    Aug 12, 2020 at 21:06
  • @TulainsCórdova Yes, but nobody writes in plain language for themselves.
    – leeand00
    Aug 12, 2020 at 21:17
  • @FrederikBanke Future developers might not be quite as familiar with the code or language and thus the plain language should be written using every day words not the tech buzzwords of the moment; those future developers might have their own.
    – leeand00
    Aug 12, 2020 at 21:21
  • 4
    Would totally agree with you if you would just strike the word "other." Half a year or more down the road, the person who wrote a commit message is just as likely as any other developer to benefit from reading it.
    – Solomon Slow
    Aug 12, 2020 at 21:56
  • 1
    Also keep in mind that the two main questions future developers will have about your code are "WTF?" and "Why?". Try to answer the Why by referencing the requirement or bug ticket that your commit intends to solve, that will make understanding it much easier.
    – Hans-Martin Mosner
    Aug 13, 2020 at 4:33

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.