> Business reasons for code changes are kept in JIRA tickets and in merge requests.
It's fine for JIRA tickets or merge requests to have the meat of the details. So this commit message:
PROJ-431: split function
is much better than just:
split function
because although git blame does not give me the reasoning directly, at least I can read the ticket and hopefully understand it in minutes. In the latter case, there might be some later commit within the merge request that does refer to the ticket number, but Git does not have a quick way of finding later commits, so you might have to muck around with the log for some time to find the actual ticket reference.
But with a commit message like:
PROJ-431: Separate base lookup and filtering
For the Foobar customer, this data needs some special aggregation
after lookup but before sending it to the main filtering function.
, it takes literally seconds between seeing a curious line of code and understanding why it was put there. Depending on how often a reader of the code has to do this, it may or may not be worth the effort. But in my experience working on decades-old projects with thousands or tens of thousands of commits, it makes a significant difference to productivity and the rate at which a new developer understands the code.
It's fine for JIRA tickets or merge requests to have the meat of the details. So this commit message:
is much better than just: because although git blame does not give me the reasoning directly, at least I can read the ticket and hopefully understand it in minutes. In the latter case, there might be some later commit within the merge request that does refer to the ticket number, but Git does not have a quick way of finding later commits, so you might have to muck around with the log for some time to find the actual ticket reference.But with a commit message like:
, it takes literally seconds between seeing a curious line of code and understanding why it was put there. Depending on how often a reader of the code has to do this, it may or may not be worth the effort. But in my experience working on decades-old projects with thousands or tens of thousands of commits, it makes a significant difference to productivity and the rate at which a new developer understands the code.