Andrei Solntsev: WTF Commit Messages

In this talk, Andre Salev delves into the significance of writing effective commit messages in Git. He begins by showcasing examples of poor commit messages that hinder understanding of changes in software projects. The speaker emphasizes that commit messages should not only describe what the change is, but also why it was made, highlighting the role of these messages in facilitating better communication among team members. He explores the potential consequences of inadequate documentation in commit messages, particularly in relation to debugging and maintaining code. Additionally, he provides guidance on structuring commit messages effectively, encouraging participants to adopt practices that ensure clarity and minimize misunderstandings in software development.

[Music] welcome back uh for all the people at attending uh this event we are back from lunch I hope that you have a great lunch a light lunch or a Super Lunch whatever you want to call it I'm again Francisco bolini from open Neola systems I'm going to be your host for the data track uh and you're watching a lot of uh talks today so we continue

on that mood of having more sessions um the next session will be started shortly it's from Andre salev I'm probably pronouncing so bad apologies for that Andre um he's author of selenite a popular open source Java library for web mobile testing he also had a black belt in iido so don't make him um too much math so please be careful with that h f extreme programming uh

I'm fine of PA programming but it's extreme is okay as well uh and he's like to give a non it speeches so welcome Andre to the devops pro Europe online welcome uh yeah thank you welcome welcome my name is Andre SF yeah I know especially for the people on the side of Europe you know it's a the west side it's a little bit complicated to pronounce sometimes

okay I'm gonna I'm gonna add the slides and I will leave you the floor to you so you can start delivering the talk thank you yeah thank you so my name is which means the son in Russian and uh a couple of first about me I am a software developer uh from thain Estonia and I'm working at company codor we use pair programming test driven development agile

extreme programming and so on and so on uh and I also love open source uh I did create few projects and do maintain some few other projects and yes I'm a fan of test dream development clean code and so one yeah and among among different projects I created selenite which is a Java library for uh web tests automated tests for mobile and web which became quite popular

and yeah here some some my contacts Twitter and site and so on so and and this is talin this is talin the capital of Estonia yeah they have quite beautiful ancient city uh so today I'm going to talk talk about commit messages in git and the plan is quite short uh I I will show some bad examples which are obviously bad then let's talk about uh why

it's important why many people do underestimate it uh importance of Comm mess and then I will show some not so obvious examples of also bad messages and if we have time we will do a little bit more practical exercise with uh rephrasing commit messages so let's start with b examples uh you probably have seen uh images like this like uh this is some uh typical git history

of some typical project uh which has in the beginning quite like readable messages and later they become shorter and shorter and less meaningful uh yeah as a project drags on my get commit messages get less and less informative probably it happens also for your project uh and for many many projects as well but but okay it's just a funny image but when I took a look at

some of working examples uh in my working projects I found quite recent commit messages like this refactor implementations and the next commit is again refactor it implementation exactly the same commit message bad bad uh uh then I found few more commit messages like fix it incorrect logic at that logging code clean up refactory configuration and so on and so on and the last one is especially unreadable

for me develop merch conflicts resolve what what the hell what do it mean nobody knows uh but but yes this example seems quite Tri and obvious and you probably seeing that yes it's obvious but and it it's not a problem for me in my case yes I don't don't write such commit messages I'm going to show some real examples uh including uh my own projects as well

so I sometimes also write some bad bad commit messages uh let's let's dive into code uh and uh try to find find something useful for from G history this is one example of play framework this is an open source project that I did separate talk about uh and that talk uh I showed one piece of really bad code one piece of code that did try and many

many lines of code and in the end just catch exception and this especially funny message that oh well probably it's compile Optimizer I hope so especially funny message and it just ignores this exception so in many aspects this is a really bad code and it cause Pro problems in production in development in testing many problems but currently it's not the topic currently topic is to talk into

history and to watch why such P code was written uh let's dive into the code this is a play framework source code uh yeah finally I found this place this the place so our uh question is currently why it was written like this uh just probably if you know you know that people don't usually watch the whole history like G show history or from command line L

it would be too long in many cases if you have int J there or Eclipse something like that it's much more convenient to annotate to annotate uh this file or in other words use G BL and it shows who recently who was the last one who committed this line and here we see the last one who committed was uh like uh my goal is not to blame

anybody not not not at all uh everybody can like make a mistakes no this is not a focus at all focus is uh commit message uh my my like uh interest is is it clear from this message what happened and why why we have to catch exceptions and uh when I found it for the first time I was really surprised because this is a very short Comm

message that doesn't really say anything uh we can even watch the diff this is local variable blah blah blah where is uhuh name Hunter if we can watch the diff and uh from the diff we also do not see why why we had the catch exception so this is just a very bright example of B commit message it says just scolar changes but nothing more we cannot

really get any knowledge from this but one thing that I uh saw that at that moment we catched only not all exceptions but only one specific exception no field exception it a little bit explains what what was the initial they wanted to catch some situation when some field doesn't exist okay but why then we catch all exceptions here this was a problem for us in production ahuh

we can we can see that some somebody other has changed this line later and let look let's look at this commit message yes I already know that at this commit uh no field exception was replaced by more generic exception which is generally a bad practice but let's look into commit message does it does it explain why this is our focus and what says this commit message it

says quite a lot of IDs ticket IDs or some issues and explains big fix for local variable enhancer so again pretty bad commit message because it doesn't really explain uh what happens what means Big Fix why so many tickets and so on and so on doesn't explain uh okay it a little bit mentions fixed local variable assignment but so what like we don't really know what happened

ah duplicate member exception bug fix again it a little bit a little bit like shows up what was the area to be fixed but it doesn't really explain why do we need to catch all exceptions uh so yeah in that sense it was bomit message uh what my point is that later we had to spend much more time to fix it to investigate why what should what

happens if I remove the sketch or what happens if I catch some specific exception what happens what goes wrong this is the information that I really wanted to get from commit message and I didn't get another example really hot topic probably you remember that two years ago already three years ago there there was one major uh vulnerability in Java Library called L forj this vulnerability was called

lock for shell and it was really disaster they found that many many interprise Java applications in the world were vulnerable due to this SP like for from day one day Zero so it was really really a problem and and uh today let's use this example uh to in investigate is it easy to understand why such a vulnerability was created how it happened uh from the about description

I know I know that this it was somehow related to gnd data source or something like that so let's look into commit message of this project this is look for J2 a very popular Java library for testing for logging let's try to find something from history with name GDI and now you see how it's not easy to read commit messages to read this G history quite a

lot of messages contain word g&i some replace some change documentation and so on and so on so this history is quite good even because many commit messages have prefix doc which says this is documentation it means for me that I can ignore them and scroll down uh something was renamed so this is quite good messes here uh and I know that the problem happened uh in December

21 like so uh now we found the first commit that that seems to to make a quick fix for this vulnerability uh restrict ldp access V and GD that was a problem ldpi access whatever and where it was discr uh restricted so this Comm message is pretty clear restrict access clear Story ID or ticket ID clear some more uh additions yeah very clear what it does clear

uh but let's through this file let's find uh how it happened this vulnerability uh looking at this commit in the end I found that the problem was with class GDI manager and in this commit we see that usages of whatever G were restricted at at this commit okay clear probably it helps us to find the very first commit that created this vulnerability yeah so so we now

know that the problem with with class G manager let's dive into this class and let's watch the G history of this class and now we can find the very yeah you can see that some of latest commits were like revert something remove something disable something uh this was exactly to solve the problem with GDI disabling GDI by default yeah very clear messages but let's find out why

it was created at all this is a classet is cause of major security problem in the world why it was created this is a very commit the very first commit where it was created uh if I remember correctly the vulnerability was here from the day one from the very beginning uh and what is a commit message commit message says at GDI manager class for use with J

JMS is it good commit message uh more or less but not not really because it's not clear why it's needed why it was needed at all also it's not clear from this commit message uh how they uh wanted to use it because this commit contains only one file no usages no tests no documentation in that sense this is really bad commit it has only one word J

GMS which probably like show his intention okay in that in this case probably the problem is that this project was migrated from subversion to git uh but still the commitment could be better uh let's uh yeah just to summarize this was a problem link link to the problem uh and commit message uh just said that an in JD manager and was wasn't clear why mm just to

uh so uh let's go on with the second uh part why are commit messages important because the problem is that all people like know that yes I need right commit messages yes uh it's like required uh but people usually don't pay really much attention to it they just write fix a test fix a Dos or something like that uh but they don't pay attention to it so

why it's really important and this is my primary goal for today uh because software developer nowadays is not about writing text for computer like these are brilliant words uh no nowadays software developer about uh knowledge exchange between people you are working in a team you making code changes for people because of people and you you want actually other people to understand why you did it you want

other people to easily maintain your project and so on and so on uh in other words it's what is really easy in our every every day work other software developers STS and so on and so on what it is easy uh it's easy to change the code it's not a problem I can always add some if to anywhere to any quote I can easily add hundreds of

lines of quot not the problem what is really hard in our work is uh to understand what exactly should be Chang it what if should I add where it should be add it uh if this if will break something these are questions that are really hard and we actually spend time and our brain resources to understand these things right uh if I see a buck in the

codes that I want to fix I trying I'm trying to understand is it really a buck or probably it was intentional uh and why why this code that I see that seems probably stupid to me why it was initially implemented like this I want to get answer to all these questions uh yeah and if I change this line of code wouldn't it make things worse than before

these are important and hard question in our everyday work right and how to get these questions easily there are uh many ways uh how people in it companies or in in all companies try to exchange knowledge between people between teams there are a few popular means uh first of all documentation Confluence jir Wei uh sharing Word documents sharing information using emails right uh and also in comments

in code people often say that you need to write comments in code which for me is generally a bad idea and I will explain why there are also underrated means that are much better for me and that are not popular uh they are the code itself the clean code is called that is expressive names of variables methods tests and so on should Express the intention should explain

what this code does without having to need any uh having to write any documentation or confidence and so unit test must must explain how this code Works what it does what is expected result and the most underrated one is commit messages uh commit messages should always explain why it was changed so uh in some sense modern software development project is like uh social network yeah uh and

all these ways are needed to uh communicate between people and this very the most popular ways are actually bad because become obsolet documentation becomes obsolet very quickly uh they usually are not up to dat uh and there are other troubles all this documentation usually contains too much info uh very often it contains controversial info and usually it's written not for you when I try to find any

answers from Confluence it's it's really hard usually because Confluence contains too much data most of it it's not interesting for me it's not useful me uh and that's why searching takes time and they cannot always find the answers uh this this illustration shows uh what happens when you try to develop uh all the time getting information from confence or documentation this is like the same when you

try to read yeah try to write the bus uh all the time reading documentation how to write the bus uh it's it's not effective right you need to get answers faster you need to quickly get answers to all your questions and this is is a part where these things are good and especially messages uh sorry once again yeah commit messages always uh contain true they cannot lie

uh never so how how should look like proper commit messages let's start from uh from a very like non nonat uh example if you ever thought how typical poish press release looks like they pay attention how to write press releases they are professional in that sense typical press release looks like this uh very no simplified but like this the header looks like this people don't swim there

is Al also the first paragraph which says poce warns water is full and dangerous bacteria avoid swimming and if you read further further there is also some explanation like why it's too hot this week that's why temperature was increasing blah blah blah bacteria started growing blah blah blah medine uh cannot fix it quickly blah blah blah so these are part of typical press release like header or

in our terms subject uh this part explains briefly what what happens what you need to know and this part explains uh some details some addition information why what what really happens details and so on why it's important because police knows that most of people will not read all this text most of people will read only header that's why they need to show the most important part in

the header some of people some percentage of people will start will start reading and read probably the next paragraph and only few who are really interested in the things we'll read the the last part uh another example from real life when uh like human comes to man comes to a woman he says very me uh this is a little bit controversial example because in real life it

happens differently usually uh but still which would be the most practical and clear message from from my opinion the very first subject line says marry me second line uh adds a short explanation yeah like we will live together and share expenses and uh we're not going to have children this is a very quickly contract or intention what happened and the last part explains some details like some

additional problems uh maybe not everyone is interested in this details so maybe many customers will read on this title and quickly accept the suggestion uh these examples show uh principles which are also applicable for commit message the very first line should be short and should quickly explain what what happened this is a subject uh let's take this uh last example from log forj framework commit message should

say disable jdi look up by default very clear very short understandable if some people are interested then they can dive into details and go to go to the bottom like and say and read the next part which little bit explains why or what happens because CH look up cost huge security vulnerability blah blah blah that's why we should disabilit it and if some people are even more

interested and go to dive and want to dive into details then they can read next chapters saying some more details and why it happened and some historical reasons and so on uh so the point is that the first line should explain briefly what what was uh speaking about this first line uh people often struggle with uh wording how exact should I say when I change it when

I disable look up should I write into commit message like this commit disables J look up or should I write I have disable J Lo up or should I write disables jup or disabled J up or J look up was disabled was disabled by me or had to be disabled or whatever or had to disable during the look up so all this uh wordings are used by

people and if you think a little bit uh they all create a hassle that's why a best practice is to uh use the shortest form of of this words the shortest form is in English is verb just plain simple verb just say disable to up not I disable not it was disabl it not this commit disables but just very simple minimalistic word disable Gile uh uh there

is a brilliant post explaining how to write commit messages let's briefly go uh through these lines uh let not of them are really important for me but some are like number first split subject and body with plank line this is uh that I already explained subject is header is Short Line and body is like some explanation uh body can contain multiple chart chapters if you want limit

subjects to 50 charts this is not important for me nowadays monitors are wider uh start subject with capital letter not important for me uh don't put dot in the end of subject again minor but again do create hassle it's not really needed this is important start with imperative rep like add button disable in J up create report imperative web is a very simple We R Body uh

not important and the most important part in the body explain what and especially wow why why it was changed uh and maybe optionally you can also explain how like some technical details but this is optional only if you need it uh let me give some hints for commit message uh people often struggling because they don't know what what exactly to say I just renam it it I

renamed it what what should I explain why it's clear some hints uh you can describe describe motivation motivation for this change why you decided to why uh you can uh describe difference with the previous Behavior like if you add added report but previously there was also report what exactly was Chang it uh and one very good practice that I personally like is uh just take a name

of the test you added in this commit or change it and just copy paste this test into commit message uh this often works and if you are going to commit files without any test bad practice stop and think twice uh also remember that I I already mentioned that your com message should answer the question why this is the most important question why you did it uh and

let me emphasize it you should answer not just question why but you should question what the what the hell you did production is broken after a commit tests are broken after a commit we're all struggling after a commit why did you this change it's a little bit dramatic but think about it IM when you do commit imagine that something really bad happens because of this commit and

this doesn't mean that you shouldn't change anything no but you should explain why why do you did it like your intention at that moment just fix it just write it down and let me remind that once once again the goal of commit message is to give uh fast answer because people can get slow answer from documentation from confence and so on and so on uh but people

want to get fast answer to work effectively like to to change code quickly and effectively that's why they need to get fast answer from commit message uh and it should also give easy answer because yes again people can read long Confluence documentation the whole day and in the end they will get the answer but they should get much easiest answerer from the commit message and with your

commit message you should try to minimize the risk of misunderstanding of risk of risk of error it must be so much clear that people people definitely will understand it correctly and will not make a mistake uh another problem with commic messages is that people often are afraid of redundancy people often think that well why should I explain my motivation in commit message if this motivation is already

explained in confence in jur task and so on and so on in comments and yes this is true these things are partially duplic each other commit messages tests variables comments and code J ticket Confluence yes these things a little bit duplicate each other this is true but let me emphasize that this is not a problem at all this is not bad at all because the things uh

describe their uh texts like in in a little bit different ways and with goals uh that why it's not a problems at all that at all that they a little bit duplicate each other it do it differently and it really helps in our work uh okay uh let me bring some examples of not so obvious changes not obvious bad commit message uh when people don't really know

what what to write this is a some real example of of real project when where I see commit called Fix texts uh and after five minutes I again fix commit fix text and it seems to be obvious if I just fix it some texts what should I describe like it's obvious should I spend time like to the explanation uh and this uh and I will just bring

some hints again let's think uh that somebody could ask you why did not you fix all the text one commit why did you need to commit the first change then spend five minutes and commit again why not all at once what happened really uh you could also think that you could answer the question why you think that second change was better than the previous one the second

text was better than previous one why who said like the answer could be Story ID G ID link to some Excel file or whatever or customer email whatever because Yes actually we often had problem that the first varant actually was better than the second and somebody mistaken again and committed the wrong text took from wrong files or whatever and just imagine that somebody comes and says hey

what you did the first text was better why did you change imagine uh M and yeah so you you try to foree all the SC questions and answer them in in the commit message not not too long it doesn't mean that you need to write long messages no no no short still uh and to think about it uh there I created a method which calls which is

called Barista method which should help in this uh case let's imagine that you are working on renaming text for example uh and after every commit you go to a coffee and there is barista uh near this coffee machine and Barista asks hey what's up what you have done who is the last commit and you answer well I fixed text again okay after some time you are doing

some work and after five minutes you have committed uh next changes and you created also commit message fix text you again you go to coffee and Barista asks again hey uh what's what now you have done and you say you say again fix it text like you just reproduce the same commit message and Barista asks bro wait wait you already did it last time what changed and

you start explaining him well you know actually last time I realized that I used a wrong Excel file I copied the wrong text actually I I made the mistake the first time for example or you might have some other explanation of course and yes coacha the this ex this is exactly the details that you could mention in the commit message what was really changed compared to commit

again let once once more uh in commit message please give context uh please say what and why was done and try to minimize understanding misunderstanding what could happen uh with somebody who will read this Comm uh and let me bring one last example uh commit message which is very very popular and ultimately wrong this is rever Commit This is a very typical example of many many projects

when you uh look into the history of the project and you see some commit saying revert blah blah blah and G or intellig you kind even automatically generates archit message yeah and when you see is a diff you see that previously we used version seven now we used version six and commit message says that this revert commit uh from for for many people it seems that pretty

obvious we red we downgraded so what to explain here but actually if you think it's it's very very important place where where actually you should why uh actually nobody knows why did you revert some previous commit it's very important to understand why did you revert what happened uh what actually should be said in such a that commit message that revert something what actually should be said uh

why it was reverted why did you revert uh what was the price for the revert I mean that this uh Commit This spray was commit was created for some reason it brought some uh feature or some it brought something useful to the project what why why did you revert it so did you lost this feature did you lost this fix what was uh if I upgrade again

this is probably the most important part I me as a next developer who wants again to update in PM in this case I want to know what happens what gets broken if I upgrade npm again so what what was that problem when you should had to revert it uh and yes I want to quickly again quickly get the answer probably that reason is already disappeared and I

can upgrade it again or I can still I still cannot I want to get quick answer for these questions all this information could be in this Reverb commit uh we have quite small time probably let's keep some more examples mhm and uh I will continue with the slide uh I found very uh great uh quote from Vlad uh which is a Java champion and great blogger uh

once he wrote this post the G commit Lo is where developers do their confessions I really liked this uh explanation uh this is uh some example of my personal project satday night uh that I wrote here and like I'm in some kind of I'm proud of it because this is a brilliant example of good commit message why I think it's good because again header says clearly and

briefly what was uh fix it work taking screenshots twice clear why and here is explanation like my confession confession here I'm saying that well actually it was a bad solution actually a hack and here I'm explaining that uh actually good solution would be like this but this is more complex it takes time canot do it this time so the whole point of my talk is not that

you are not allowed to mistake sure you are we all mistake why not but you are uh you you should explain this if you're not sure if this is good solution explain this if you see that you should change it because of who explain it just mention it what was the intention what reason uh if you have five minutes uh uh I would try to do this

practical examp exercise to squash or not to squash there are two kinds of people uh one group of people prefers to squash all commits of a branch to merge to a single commit uh even G GitHub suggested by as one default option one of default options and there are people who prefer not to squash commits and merge all commits all the commits from all the history uh

to let leave it at it so uh use the full history uh both approaches have some uh problems if in case if you squash all commits you you might lose some important information and in case if you do never squash commit you uh in some kind you disrespect your colleagues you are spamming them you are adding to gitl git history to many of minor changes some fix

tests fix text and so on and so on and what is my way what I suggest I suggest to do uh rebs and uh uh always when when you finished some work on some feature branch on some feature and you think you are ready to merge this Branch please review this Branch I usually do it I review all this branch and I try to uh keep independent

changes in separate commits and uh fixes without own value like fix tests and so on to squash them to a single commit and of course update commit message of each of these commits to make it readable uh yeah in other words makes your colleagues happy and show respect to them uh I would ask if you have some time or we have lots of questions no we have

some time uh you have a couple of three minutes something like that so if you want to go and practice uh I mean do some demo and all that I'm not seeing questions in the chat or the qu ah yeah I have one here oh my sure yeah jaob jaob Rosa is asking uh what about when we can only verify changes with CI and we have to

do very many to do very many small commits it is impossible to test it locally because everything is behind several firewalls and only from the pipelines we can verify this change often during such comits we change only one parameter and test if it will eventually work uhuh for example we are not sure if some syntax will work correctly for example in anible or gitlab okay thank you

for a question first of all this is a really a organizational problem uh if you cannot run tests locally this is a huge problem you need to solve it independently of G and commit and messages uh you need to to be able to run this locally definitely this is very important but still uh getting back to the question yes this is exactly what I want to show

that initially when you are working on feature Branch you can uh create many commits uh uh try this parameter try this parameter try to rename variable whatever but in the end when you are Branch uh I recommend to do interactive rebat what it means this is a Fe feat of git or intell there that allows you to review all these commits and to put some of them

into the single commit and rename commit message uh which allows you to create a nice G history this is exactly what I wanted to try uh okay probably it takes it takes time uh okay let's let's assume that I created some small commit and committed let's assume that I created another commit fix it something try it another parameter uh did it let's assume that I created a

third third parameter this is some par to committ it also and and probably I get back to the first line to the first file and I realized that well I did break the test probably I wanted one minor thing test at this point fix test something like that so now we have history of four commits and for example many of them are like try parameter this PR

parameter that and so on and so on so now I am able to finish my work so that uh I'm not going just to push but I want to make this history uh great again so let me uh call get base oops G base M and this is a very important part this is name of main branch and very important part to select here interactive this is

a g interactive rebase very important feature so I enable this inter interactive mode click rease and what I see now I see a list of my commits that are going to to be pushed or to to be mered and I can now reorder of them for example this one was the fix for the very first Commit This means that I can move it up and I can

even uh click option fix up and fix up means that this commit will be merged into this Commit This was fixed like for this commit and probably I might also realize that these two commits change like very similar thing probably so I also might be uh scor them so instead of those two uh I create one commit and I renamed it I have renamed this commit uh

and now if I have conflict then I have a very readable clear uh G with independent commit everyone has having a good commit message this is my way cool cool no very clear very clear I think it's it's clearer than the usual and I was going to ask stuff but the thing is that yeah sure I was but we are running out of time to be honest

Andre and and and thing is super interesting I think that uh people can reach you over Twitter or what do you prefer the social network that you prefer to use I don't know if it's Twitter or LinkedIn oh sure I have some contacts yes yeah okay Twitter okay you have it here okay perfect yeah thanks thanks a lot for your for your presentation uh very useful for

people that are doing programming on their daily basis I I know people that are making lame comments on on code so that's another another another talk that we can that you can think about it uh not only on comets also on during the code which is even even worse um thanks a lot um we are running completely out of time but it was super useful uh thank

you for being here with us participating on the devops pro um I'm gonna tell the attendees that we have the next session in around 13 minutes uh it will be the next session with Muhammad shmid uh so stay tuned or you can watch the rest of the the rest of the devops pro uh agenda in the in the pine event so thanks again Andre hope to see

you in other events and sure for the people attending uh we'll back soon in 10 minutes bye-bye bye for