What's harder than choosing a variable name? IMO its composing a perfect code comment and commit message. Today we will discuss some bad commit messages, why they are bad and what we can do to improve those?
You made all the code updates, wrote tests and now its time to commit them with a commit message. Is "Code Updated" a sufficient? What about "Issue fixed"? Just imagine yourself reading the commit message some time later. Just like code comment, commit message should add context about why the code update was necessary?
A good commit message helps a future developer(it might be you) to reestablish the context around a piece of code whenever the developer needs to dig through the history to find out why the code was changed. It also helps the code reviewer to what to expect on the code.
Unless your team follows squash merge (where all the individual commits in the PR are combined and the person merging the PR can put a single/meaningful commit message) you should pay extra attention when choosing. Commit messages like the following add no value. A good developer should never write these kind of commit messages.
Bad commit messages(taken from real life examples):
- issue fix
- more changes
- logic updated
- updated code again
- added import function
- updated dialog box UI
- deleted column
Good practices:
Describe why the code was updated?
"Issue fix" doesn't indicate which issue number and what was the cause of issue? "Logic updated" is super obvious and serves no purpose. "updated dialog box UI" doesn't indicate which dialog box and why it was updated. "added import function" doesn't indicate which data type does it import?
Refer the Issue/Jira/Story number
All the code changes should be followed by a Jira/Story created by someone. Noone should just go ahead and make a arbitrary code change. Most of the git providers (github, bitbucket, gitlab etc) support hyperlinking of Jira/Issue number from commit message. eg: UI_APP:4555 Fixed broken button on IE9 caused by unsupported JS function
Commit frequency: per logical change
Its good to do a new commit per logical change. eg: do a commit once the functional piece is working:
- new column 'purchase_amount' added on table
- updated the backend to save new purchase_amount column
- updated UI to display new column
For bigger update, use a heading and bullet points. The header can be short.
Commit frequency: commit often to have a periodic checkpoint
Imagine you are working on a BIG feature where you modified several files. At some point you are able to make few things working (point X). But when you work on additional changes the things that worked earlier started breaking. Later you are in a position where you don't know how to revert the new changes to get back to the point X where few things were function. If you had committed your changes at point X, it would have made it super easy to revert local changes to that point.
Few good examples:
- dialog box UI updated to support multiple callback functions on both Cancel and Save event –> instead of updated dialog box ui
- removed the employer contribution period field as we're no longer using it –> instead of removed employer contribution period field
- add member import function for the employer user –> instead of added import function
No comments :
Post a Comment
Your Comment and Question will help to make this blog better...