assert: add comments for diff algorithm

It became hard to follow what was actually happening in the
algorithm. This adds comments to improve the situation.

PR-URL: #23048
Refs: #22763
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Shingo Inoue <leko.noor@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

lib/internal/assert.js

@@ -174,6 +174,9 @@ function createErrDiff(actual, expected, operator) {
     // Only extra expected lines exist
     const cur = i - lastPos;
     if (actualLines.length < i + 1) {
+      // If the last diverging line is more than one line above and the
+      // current line is at least line three, add some of the former lines and
+      // also add dots to indicate skipped entries.
       if (cur > 1 && i > 2) {
         if (cur > 4) {
           res += `\n${blue}...${white}`;
@@ -185,11 +188,16 @@ function createErrDiff(actual, expected, operator) {
         res += `\n  ${expectedLines[i - 1]}`;
         printedLines++;
       }
+      // Mark the current line as the last diverging one.
       lastPos = i;
+      // Add the expected line to the cache.
       other += `\n${red}-${white} ${expectedLines[i]}`;
       printedLines++;
     // Only extra actual lines exist
     } else if (expectedLines.length < i + 1) {
+      // If the last diverging line is more than one line above and the
+      // current line is at least line three, add some of the former lines and
+      // also add dots to indicate skipped entries.
       if (cur > 1 && i > 2) {
         if (cur > 4) {
           res += `\n${blue}...${white}`;
@@ -201,23 +209,40 @@ function createErrDiff(actual, expected, operator) {
         res += `\n  ${actualLines[i - 1]}`;
         printedLines++;
       }
+      // Mark the current line as the last diverging one.
       lastPos = i;
+      // Add the actual line to the result.
       res += `\n${green}+${white} ${actualLines[i]}`;
       printedLines++;
     // Lines diverge
     } else {
       const expectedLine = expectedLines[i];
       let actualLine = actualLines[i];
+      // If the lines diverge, specifically check for lines that only diverge by
+      // a trailing comma. In that case it is actually identical and we should
+      // mark it as such.
       let divergingLines = actualLine !== expectedLine &&
                            (!actualLine.endsWith(',') ||
                             actualLine.slice(0, -1) !== expectedLine);
+      // If the expected line has a trailing comma but is otherwise identical,
+      // add a comma at the end of the actual line. Otherwise the output could
+      // look weird as in:
+      //
+      //   [
+      //     1         // No comma at the end!
+      // +   2
+      //   ]
+      //
       if (divergingLines &&
           expectedLine.endsWith(',') &&
           expectedLine.slice(0, -1) === actualLine) {
         divergingLines = false;
         actualLine += ',';
       }
       if (divergingLines) {
+        // If the last diverging line is more than one line above and the
+        // current line is at least line three, add some of the former lines and
+        // also add dots to indicate skipped entries.
         if (cur > 1 && i > 2) {
           if (cur > 4) {
             res += `\n${blue}...${white}`;
@@ -229,14 +254,21 @@ function createErrDiff(actual, expected, operator) {
           res += `\n  ${actualLines[i - 1]}`;
           printedLines++;
         }
+        // Mark the current line as the last diverging one.
         lastPos = i;
+        // Add the actual line to the result and cache the expected diverging
+        // line so consecutive diverging lines show up as +++--- and not +-+-+-.
         res += `\n${green}+${white} ${actualLine}`;
         other += `\n${red}-${white} ${expectedLine}`;
         printedLines += 2;
       // Lines are identical
       } else {
+        // Add all cached information to the result before adding other things
+        // and reset the cache.
         res += other;
         other = '';
+        // If the last diverging line is exactly one line above or if it is the
+        // very first line, add the line to the result.
         if (cur === 1 || i === 0) {
           res += `\n  ${actualLine}`;
           printedLines++;
@@ -246,7 +278,7 @@ function createErrDiff(actual, expected, operator) {
     // Inspected object to big (Show ~20 rows max)
     if (printedLines > 20 && i < maxLines - 2) {
       return `${msg}${skippedMsg}\n${res}\n${blue}...${white}${other}\n` +
-        `${blue}...${white}`;
+             `${blue}...${white}`;
     }
   }