Git- and Diff-friendly Code Comments/Spacing

[2022.10.21]

I am a maniac but …

I regularly get sighed upon when I comment on GitHub Pull Request and I insist on sticking to what à priori seems a weird (even anti-pattern) code commenting convention:

• use 3 (three) comment/blank lines before 1st-level code sections

• use 2 (two) comment/blank lines before 2nd-level code subsections

• use 1 (one) comment/blank lines before 3rd-level code

Even though I am a maniac, there is a (good) technical reason to do so.

Meet unified diff

Code comparison nowadays rely heavily on so-called unified diff - diff -u - which defaults to outputting 3 (three) lines of “unified” content when comparing a file for changes.

Such an output will be familiar to anyone used to work with Git(Hub/Lab):

diff --git a/foo b/foo
index 0058b60..2c79aba 100644
--- a/foo
+++ b/foo
@@ -11,7 +11,7 @@

 # Code A.1.a
 function A1a() {
-  # some operation
+  # some other operation
 }


@@ -19,12 +19,12 @@ function A1a() {

Meet partial Git add

Leveraging 3-line unified diff internally, Git partial file addition - git add -p - allows to selectively add “individual” changes, as identified/separated by @@ ... @@ diff blocks:

$ git add -p foo 
diff --git a/foo b/foo
index 0058b60..2c79aba 100644
--- a/foo
+++ b/foo
@@ -11,7 +11,7 @@

 # Code A.1.a
 function A1a() {
-  # some operation
+  # some other operation
 }


(1/4) Stage this hunk [y,n,q,a,d,j,J,g,/,e,?]? 

… there is a good reason!

Single-spaced code

Consider the following code (in bar file):

# Some
# Very
# Long
# Header

function A1a() {
  # some operation
}

function A2a() {
  # some operation
}

function A2b() {
  # some operation
}

function B1a() {
  # some operation
}

function B2a() {
  # some operation
}

function B2b() {
  # some operation
}

In case every function gets changed, the unified diff and (un)partial Git add would look like:

diff --git a/bar b/bar
index d3114aa..abe1b72 100644
--- a/bar
+++ b/bar
@@ -4,25 +4,25 @@
 # Header

 function A1a() {
-  # some operation
+  # some other operation
 }

 function A2a() {
-  # some operation
+  # some other operation
 }

 function A2b() {
-  # some operation
+  # some other operation
 }

 function B1a() {
-  # some operation
+  # some other operation
 }

 function B2a() {
-  # some operation
+  # some other operation
 }

 function B2b() {
-  # some operation
+  # some other operation
 }

See it ? All your changes are considered a single change block (@@ ... @@) and may only be added “as-a-whole”.

Better-spaced/commented code

Now, consider this code (in foo file):

# Some
# Very
# Long
# Header

####################
# Code Section A
#

## Code Subsection A.1

# Code A.1.a
function A1a() {
  # some operation
}


## Code Subsection A.2

# Code A.2.a
function A2a() {
  # some operation
}

# Code A.2.b
function A2b() {
  # some operation
}



####################
# Code Section B
#

## Code Subsection B.1

# Code B.1.a
function B1a() {
  # some operation
}


## Code Subsection B.2

# Code B.2.a
function B2a() {
  # some operation
}

# Code B.2.b
function B2b() {
  # some operation
}

In addition to:

• providing good visual clues how the code is structured (even more when using syntax/comment highlighting)

• giving many opportunities to comment all the weirdness of your code

You get a very nice-looking unified diff:

diff --git a/foo b/foo
index 0058b60..2c79aba 100644
--- a/foo
+++ b/foo
@@ -11,7 +11,7 @@

 # Code A.1.a
 function A1a() {
-  # some operation
+  # some other operation
 }


@@ -19,12 +19,12 @@ function A1a() {

 # Code A.2.a
 function A2a() {
-  # some operation
+  # some other operation
 }

 # Code A.2.b
 function A2b() {
-  # some operation
+  # some other operation
 }


@@ -37,7 +37,7 @@ function A2b() {

 # Code B.1.a
 function B1a() {
-  # some operation
+  # some other operation
 }


@@ -45,10 +45,10 @@ function B1a() {

 # Code B.2.a
 function B2a() {
-  # some operation
+  # some other operation
 }

 # Code B.2.b
 function B2b() {
-  # some operation
+  # some other operation
 }

Where each code (sub)section is ideally identified as a separate diff block (@@ ... @@), which, in addition to make code reviewing easier (thanks to the comments and visual clues mentionned above, also allows to flexibly add/commit changes partially:

$ git add -p foo
diff --git a/foo b/foo
index 0058b60..2c79aba 100644
--- a/foo
+++ b/foo
@@ -11,7 +11,7 @@

 # Code A.1.a
 function A1a() {
-  # some operation
+  # some other operation
 }


(1/4) Stage this hunk [y,n,q,a,d,j,J,g,/,e,?]? 

Or what ?

Or maybe that’s just me…