Wisdom of the Ages

A great tale to be bestowed upon the most pedantic of mortals.

Prelude

A pedantic developer cannot be more pedantic than the computer she/he is developing for, by definition. If you think your ever being too careful then just quickly remind yourself the last time you screwed up to cleanse yourself from that presumptuous tone of "never will break for me". Ready yourself..

History

Commits are actually more about the future than they are about the past, particularly in small teams with a quickly moving target code-base and a highly dynamic/fluid requirements charter.

• On the business side; One should consider git commits as an integral part of the management of incorporating constantly pivoting business decisions into the raw development life-cycle.

• On the software side; One should consider git commits as an integral part of the management of laying out the work ahead for incorporating design complexity into tangible workable code.

It is easy to be satisfied with what you have already done in a given commit however it is harder to anticiple what you would need to do next. Not unlike chess, a good player plays a good move, a great player plans a good move.

Problems not Solutions

Developers should re-consider what a git commit is in essence. A commit isn't a solution you are introducing, it is another problem. Users do not see solutions, they only see problems and users generate revenue which allows you continue on.. The development life-cylce should then be more inclusive of this fundamental dimension of the overall end product.

Every commit will introduce a problem, sometimes many problems! The task you have is to break these problems (not solutions) into smaller granulated problems. This means that you can more quickly and decisively pin-pointed the problem (with git bisect) to a particular commit.

Whats more, you would like the ability for a lesser technical person to be able to investigate a problem without needing to understand how to fix it! A user for example could run git bisect and find the bad commit for the customer, validate which commit causes that customer to become upset and forward that on to the development team. This introduces parallelism as the development team doesn't need to stop what its doing to investigate an issue.

By virtue of doing some pre-work on each commit to break down problems you maybe introducing in each commit you have then already done the fault finding for the future in advance.

Lastly, having multiple problems in one commit causes tracking down a particular issue very hard as the problems may conflate together in such a way that the problem is only exposed in later, seemingly innocuous commits.

How small is a is a "small commit"?

Small commits mean to say small in complexity in what they are trying to archive not necessarily size. This can be very confusing because of the overloaded term "small", this confusion is made worse because 'small in complexity' often means 'small in terms of LOC' and so there is a overlap.

A good metric to have in mind is to say to yourself "can I write a unit test with a boolean function that tells me the answer to the following question.." - "Can I tell absolutely this change does or does not change behavior X?". The idea here is that, one of your commits will break something in some strange way that took a lot of time you never want to spend again. As such, you want to take this commit and put it on your wall of shame, write a unit test and add it to your CI, if a commit ever tries to introduce the regression again it will be picked up.

In summary, a small commit means to say 'changes one and only one functional element of the code at any time' and ideally does it in the least number of lines to change as possible to avoid 'churn'.

Churn - why do you care?

Who cares if I change whitespace in a commit right? Wrong! Here is why, git revert. You absolutely want to be able to revert your problem commit (not solution commit) without causing a conflict. The rational here is that the conflict resolution itself could introduce a problem.

Further still, concise commits are easier to review as the human eye and brain are not perfect. You must plan that your perception of the code your looking at on the screen has bugs too.

Bugs everywhere!

They are in your brain, eyes, text editor, compiler, hardware and customers perception on what they think your delivering and what you are delivering. Heck, customers can sometimes even mistake your bugs for their features.

Assume the world is going to hell and your going to (because it is).. Once you let this wash over you, and the last shards of optimism dip away you will be ready to adopt this bold new way to develop in a world where everything is against you (brain, eyes, text editor, glow of screen, compiler, hardware, customer, boss, github wiki pages).

~ see you on the other side, Edward O'Callaghan.