> nobody at Microsoft ever understood how the code worked (much less still understood it), and that most of the code was completely uncommented, we simply couldn't figure out why the collision detector was not working. Heck, we couldn't even find the collision detector!

This continues to be one of my pet peeves, particularly with code samples and a lot of what is posted on Github, even major libraries. Almost no comments, background or guidance on the intent and structure or the code.

No, I am not suggesting that something like this is necessary:

// Iterate through all elements
for(int i=0; i < count; i++
{
// Check that velocity isn't above threshold
if(velocity[i] > THRESHOLD)
{
// Limit velocity
velocity[i] = THRESHOLD;
...

That's ridiculous. However, something like this is useful:

// Bounds-check velocities
for(int i=0; i < count; i++
{
if(velocity[i] > THRESHOLD)
{
velocity[i] = THRESHOLD;
...

Anyhow, dumb example I pulled out of thin air.

I've heard some say "I just write self-documenting code". That's a myth but for the simplest of structures. Any non-trivial piece of work is far from being self-documenting. Code is self-documenting for the guy who wrote it. I guarantee you that anyone else reading it has to reconstruct a stack in their head to understand what the hell is going on. That's not self-documentation. I shouldn't have to think to understand what a chunk-o-code is doing. The same for functions and/or methods.

The myth of self-documenting code is easy to demonstrate if I show you a piece of code in a language you don't know. I am going to assume that most programmers these days don't know assembler, Forth or Lisp.

(defun GetPolylineEndEntities ( plename / plends cvcenter cvsize oldcmdecho pt1 pt2 endss outlist)
(setq plends (GetPolylineEnds plename))
(setq cvcenter (getvar "viewctr")
cvsize (getvar "viewsize")
oldcmdecho (getvar "CMDECHO")
)
(setvar "CMDECHO" 0)

(foreach point plends
(progn
(setq pt1 (add2d point '(-0.0125 -0.0125)))
(setq pt2 (add2d pt1 '(0.025 0.025)))
(command "zoom" "c" point 2)
(setq endss (ssdel plename (ssget "C" pt2 pt1)))
(setq outlist (append outlist (list (ssname endss 0))))
)
)
(command "zoom" "c" cvcenter cvsize)
(setvar "CMDECHO" oldcmdecho)
outlist
)

I wrote this twenty years ago. Even if you understand Lisp you'd have to think it through. However, this is not how I wrote it. This is what I actually wrote:

;=====================================================================================================
; GetPolylineEndEntities
;
; Argument: Polyline entity name
; Return: Two element list containing the first (if any) entity found at the end of the polyline.
; The polyline itself is excluded.
; If nothing is found at a particular end, that element in the list is set to nil.
;
(defun GetPolylineEndEntities ( plename / plends cvcenter cvsize oldcmdecho pt1 pt2 endss outlist)
(setq plends (GetPolylineEnds plename)) ;Get the endpoints

(setq cvcenter (getvar "viewctr")
cvsize (getvar "viewsize")
oldcmdecho (getvar "CMDECHO")
)
(setvar "CMDECHO" 0)

(foreach point plends
(progn
;Examine what connects at each end
(setq pt1 (add2d point '(-0.0125 -0.0125)))
(setq pt2 (add2d pt1 '(0.025 0.025)))

;Zoom to the end being analyzed to have better selection accuracy
; **** Have to figure out a way to do this without zooming ****
(command "zoom" "c" point 2)

;Eliminate the original cable from the resulting selection set
(setq endss (ssdel plename (ssget "C" pt2 pt1)))

;Add the first entity found to the output list
(setq outlist (append outlist (list (ssname endss 0))))
)
)
(command "zoom" "c" cvcenter cvsize)
(setvar "CMDECHO" oldcmdecho)
outlist
)

Even if you don't know Lisp you now have an idea of what this code is doing. My style has changed over the years. This isn't my best example, but it is here to drive a point home.

The use of an unfamiliar language serves to illustrate the point that the idea of self-documenting code is, again, a myth. I wrote that code myself and without the comments I'd have to mentally reconstruct every step to even begin to understand what's going on and what the intent was. I haven't touched Lisp in quite some time.

I've looked through so much code in Github without a single comment that it makes me wonder if this is what is being taught in schools these days. Accurate in-code documentation is, as far as I am concerned, part and parcel of becoming a professional programmer. It recognizes that the work represents a huge investment in time, money and intellectual effort and it ensures that this effort and expense doesn't have to be duplicated in order to maintain, evolve or migrate the product as the Microsoft example clearly demonstrates.