Commentary

(it: EnvironmentedProc.rb @ b524418, lines 78 ‒ 97)

When a particular portion of code is complex or difficult enough to understand, I find it advisable to go overboard on commentary and explanation. By swamping one or two lines of functionality with twenty lines of explanation, we visually convey to the reader that “we know this is complex, and we’re going to do our damnedest to help you understand it.” Before they even begin to read the commentary or associated code, we can ease their mind by dispersing the smallest amount of code possible amongst the largest amount of explanation we can write.