Commenting Code

08/14/2021

I've often heard from some (bad) programmers that commenting code is useless since the comments often fall out of sync with the code. This is a terrible excuse, since it's just laziness to not update ALL the code (including the comments) when changing code. I've heard it argued that you should write self documenting code by picking good variables names. While this certainly helps, it does not remove the necessity for comments. Code does not convey intent in the same way that a good comment can. I recently was profiling some of my meshing code when I found the following block of code:

uint64 addr1 = (uint64)pHead;
uint64 addr2 = (uint64)pTail;
uint64 value = ((addr1 + addr2) * (addr1 + addr2 + 1)) / 2 + addr2;
m_vertToEdge[value] = pLeftHalf;
m_vertToEdge[value] = pRightHalf;
return m_edges[m_edges.size() - 1];

I stared at this code for a bit thinking what the hell is the line "uint64 value = ...." doing?? Mind you this is code I had written. Luckily, else where I did find a comment to myself that indicated this was performing Cantor pairing.

Simply adding the comment:

// Use cantor pairing to come up with hash value
// For complete description of cantor pairing see:
// https://en.wikipedia.org/wiki/Pairing_function#Cantor_pairing_function

Could have saved me a bunch of head scratching.

Also, there is a bug (assigning m_vertToEdge twice) that I found, so I guess there was one upside to not having it commented :-P