Code history is like a narrated history of code.  The ability for git rebase to reorder, rework and polish commits allow a developer (and code reviewers) to curate the code history so that it tells a well structured story.  This post will wander through how strongly the analogy can work.

TL;DR version in the slides.  Read on for the long form.

Consider the following edit mark example taken from TheRoomMom blog.

This is fairly typical of a well reviewed paragraph.  If we take the code review as an analog of the literary review, we can find some startling similarities.

Edit Marks & Code Fixups

Imagine picking up an expensive technology reference book, and flicking through the pages.  If you saw the edit marks similar to the picture above, you’d want to put the book down and would consider it unfinished.

Likewise with code, as it it evolves, it needs to be tweaked, re-written improved and polished.  Other developers don’t want to see “fixup” messages in the code.  With git there is no need to keep those fixup messages.  Squash them into other related commits to make the code look curated.

Grammar, Syntax and Consistency

When you are reading text, simple speling mistakes and accidenlty transposed letters make it difficult to maintain tempo while reading.   Using hte tech reference example above, a book that is lttered with poor grammer makes it difficult to stay focused on the topic when you are continually stopping and metnally fxing up seely mistakes that could be prevented with crae.

In. the WRItten Word, syntax     is just as imORTant!.  Thes e words are all  spe;lt correctly – but the s y n t a x and con. sis. ten. cy is bad.  (Likewise) this;

makes it ver-y hard, t   o ;re, ad quicklyand foc-us o,n th eactual con-tent.

(Hopefully you get the point by now).

The paragraphs above carry strong similarity to code that has poor formatting, sloppy structure, spelling mistakes and so on.  If there is effort to read and interpret the code, then the algorithm and correctness of the code become a lot harder to understand.

Paragraphs & Commits

When you look at almost any written form, there will be paragraphs that group text together.  Wikipedia’s introduction on paragraphs states

A paragraph … is a self-contained unit of a discourse in writing dealing with a particular point or idea.

Paraphrasing we can define a git commit as

A commit is a self contained collection of source changes dealing with a particular point or idea.

Note that git’s capability to rebase and rewrite commits differentiates a git commit from a historical definition of a commit as a snapshot of code at a particular time.

This implies that when you look at a single commit, you are seeing a coherent collection of changes associated with a single point or change.  In the same way that an endless paragraph is difficult to extract a strong view of a singular point, a commit that has many changes is almost impossible to mentally collate and comprehend.   Similarly a series of naked sentences are just as difficult to pull together a coherent idea from.

Chapters and Merges

The final area worth discussing is considering the equivalence of chapters in a book, to a merge.  Particularly in reference books, a chapter will cover (in paragraphs) a broader topic.  If you are reading about the syntax of a programming language, you wouldn’t expect to find a paragraph covering memory management.  It simply doesn’t fit.

The same with code, if you use pull requests to land code, you should treat the pull request and merge as a single chapter.  If there are commits (paragraphs) that are out of place, cherry pick it into a different branch for a different merge.

The Art of the git Squash

So when you are preparing code to be merged into a codestream, look to see if the story is present.  Here are some guidelines to help write a story with code.  git rebase -i allows you to do the following

• Look at the full diff
  • Fix the spelling, grammar, syntax and structure.  Make it look good.
    • Make the fixes, commit them and then squash the fixes with the original code changes
  • Look for code that doesn’t fit into the topic of the merge.   Pull unrelated changes out.
    • Create a new branch, and cherry pick the change and then delete the line from the rebase.
• Look at the commits
  •  Do the commits tell a logical, linear or chronological story?
    • Reorder the commits to tell the story
  • Are the commits a reasonably small, atomic collection of related changes
    • squash, edit and rework the commits.

Following these and other best practices, will help your changes be grokked by your peers, and your future self will understand what you did 12 months ago.