Ensuring you code is readable is arguably one of the most important things you can do after ensuring it is correct. The real question is: readable to whom? Because apparently, some people have odd ideas about readability. Like Evan's co-worker.

/* dlgAdvanced.vb */
Me.btn1.Text = "Yes to All"
Me.btn1.DialogResult = Windows.Forms.DialogResult.Yes And Windows.Forms.DialogResult.Ignore ''Easy Readability, but the real value is 4 (DialogResult.Retry)

It's easy to see that the comment is partially accurate: Yes is 6, Ignore is 5, so ANDing them together will leave us with 4. And also, 4 is indeed Retry.

The portion of the comment that isn't accurate is "Easy Readability". Easy for whom? How is this easier than just using Retry?

Worse, this pattern is used all over the codebase, and each time it's used, it needs to be documented as having "Easy Readability", because if you say it enough times, it eventually becomes true.

[Advertisement] Otter - Provision your servers automatically without ever needing to log-in to a command prompt. Get started today!