1. 26
  1. 9

    I’m also often encountering a very serious problem, but missed and didn’t taken seriously most of the times: commit messages.

    Senior developers (especially those from 90s, who worked with CVS or Subversion in small teams) usually act like a monkeys when set up in front of Git. Instead of getting the model of operation for this particular SCM, they memorize “magic commands” to “do stuff”. sometimes even dangerous or destructive locally. But that can be sometimes get softer by using SCM integration in major IDEs.

    But no one can force them to write proper messages. Every time I’m getting into some project made by more than 2 people, I can’t figure out what was done. Instead, I’m sinking in sea of commits called “fix” (in various forms), “adding xyz” (and modyfing the half of source tree), “commit” (yes this was an actual one) and many others, even mixing languages (this deserves another kind of rant too). Of course don’t expect extended messages too.

    When I do commits, I’m always making them in form of answer to question “What this commit would do?”, and valid answers can be, for example, “Correct a typo in main class” or “Add a SuperMegaClassManagerFactory by request WTF-2137” (and describe it in extended message). If it comes to very large project (like, for example, configuration management repos) it’s sometimes nice to add single keyword prefix to narrow the topic, like “soup: Add tomatoes, generate new recipe”.

    For people working with single repoistory (or monorepos) it’s very helpful to get something such as git-standup which gives you a very helpful reponse to “What did I do in this week” question. And it might teach these people something, as they’ll probably see wall of “fix”-es :)

    1. 6

      I was thinking about how we also could transpose this to FOSS projects. Maybe instead of using bug solving as an excuse to go though a new code-base we could use code-review.

      I’ll give it a try.

      1. 3

        It’s a great way to start contributing to a codebase. Highly recommended.

      2. 6

        Yes! I’ve learned easily as much from reviewing CR’s from Sr. Engineers on my team as I have from their feedback to mine! The best ones I worked with even appreciated the feedback I could offer, and reinforced important lessons about giving honest feedback.

        There was one instance in particular where I had a question about part of the implementation, but left it unasked, figuring they already thought through that case and that their current implementation would address it. When a bug came up later I offered the Senior the solution and mentioned I had wondered during my review. They were able to stress to me that although experienced they weren’t above mistakes, that they saw value in my reviews and I should be pointing things like that out. It was a very valuable lesson for a dev with 1-2 years experience that has also stuck with me now as I’m at a mid-level working with engineers both my junior and senior.

        1. 4

          I think that one additional benefit of this approach is, that things that as a senior dev seem obvious and don’t seem to need documentation or commentary, might not be as straightforward as thought and the reviewer can help to point that out by questioning the approach.

          It’s a win-win because as a seniority progresses one might loose the view of what the presumable status quo is. In the time before becoming a truely senior dev, I tended to over complicate things however learning later, that the real solution could be much more simple. When a junior points out that things are quite complicated, it might be a good pointer to revise the code to be more straightforward. This in turn should or could lead to a better understandable code base.

          1. 2

            Those that see other people’s mistakes are doomed to repeat them…? I know “junior” devs who write better code and better commit logs that 20y old veterans.

            1. 1

              I found myself in this position a lot at work, and wrote a post about to be useful when you’re in the junior developer tasked with reviewing code from people who know the system better than you do - because it can be intimidating and difficult!!

              https://maxbittker.github.io/code-review/