When working with code that deals with matrices, it is sometimes necessary to represent a matrix on the commenting lines of the code. Matrices have standard mathematical notation but unfortunately the notation is not trivial to reproduce with ASCII characters and monospaced font typical to source code. Therefore, mainly for my own reference but also possibly for you fellow coders, here are some of my attempts to represent matrices first with plain ASCII and then with some Unicode characters. The aim is to style the matrices in the comments well, so that they look good to both the readers of the source code and the readers of the documentation that could be generated from the codebase with tools such as JSDoc.
First the widely practiced LaTeX powered notation generated with Online LaTeX Equation Editor:
Then an initial attempt to reproduce the notation in plain ASCII:
| a -b x | | b a y | | 0 0 1 |
The pipe symbol “|” does the job. However, in some situations the notation could be confused with the matrix determinant that also uses vertical lines instead of the square brackets. The determinant is a property of matrix and they are not equal.
How to make the ASCII notation to resemble the wide brackets?
[ a -b x ] ( a -b x ) [ b a y ] ( b a y ) [ 0 0 1 ] ( 0 0 1 )
By using the square brackets or parentheses, the determinant notation is probably not the reader’s first guess anymore. However, now the notation hints to arrays, lists, or tuples, commonly represented by the square brackets and parentheses in the programming languages such as Python and JavaScript. We would like to avoid such misinterpretation. More attempts with plain ASCII:
+ a -b x + _ _ +- -+
| b a y | | a -b x | | a -b x |
+ 0 0 1 + | b a y | | b a y |
|_0 0 1_| | 0 0 1 |
+- -+
The first one from the left with the plus signs is just awful. The second at the middle is surprisingly neat regardless it consumes one extra line at the top. The third one is okay, at least to my eye but quite verbose. Sometimes matrices are also represented with long parentheses instead of brackets. Could we imitate that with slashes?
/ a -b x \ /a -b x\ | b a y | ( b a y ) \ 0 0 1 / \0 0 1/
Interesting but I think they begin to look like some kind of UFO sighting in an ADOM world. Maybe the ASCII character set is just too limited. Unicode to the rescue!
Unicode provides us lots of characters from to choose. Let us try to reuse the symbols for ceiling and floor operations with the pipes at the middle:
⌈ a -b x ⌉ | b a y | ⌊ 0 0 1 ⌋
Quite good although the vertical lines are a bit misaligned. Let us do another attempt with the box-drawing characters that originate from IBM PC era and are a solid part of the Unicode standard:
┌ ┐ │ a -b x │ ┌ a -b x ┐ │ b a y │ │ b a y │ │ 0 0 1 │ └ 0 0 1 ┘ └ ┘
Not perfect but maybe the best this far! Let us still try one thing and combine the height of the ceiling and floor symbols with the long vertical pipes of the box-drawing characters.
⌈ a -b x ⌉ │ b a y │ ⌊ 0 0 1 ⌋
Nah, the vertical lines still do not match.
As a result, I feel the box-drawing characters ┌└┐┘│ provided the best presentation for the matrix notation. Let us conclude by applying it to a larger 6×5 matrix with additional balancing spaces on the sides:
┌ ┐ │ a b c d e f │ │ g h i j l m │ │ o p q r s t │ │ u v w x y z │ │ 0 1 2 3 4 5 │ └ ┘
Copy the following to easily adopt this template to your code:
┌ ┐ │ │ └ ┘
What do you think? If you have any thoughts, hit me with a comment below.
