You pick a file from a mass of files, hoping to get your bearings, but open it to find endless low-level manouevres. There are some suggestive class or function names but it’s hard to get a sense of even the basic plan of how it works.
This problem is made worse, I think, by the aesthetics, or perhaps I should say the ideology, of many working programmers. All programming languages provide for comments, but coders often want to purge this marginalia, disliking any verbose comment as a form of ‘cruft’. It violates, they would say, the ‘Don’t Repeat Yourself’ maxim.
This is my pet peeve: coders who don’t comment their code. I’ve got one guy here who says “well, my code is self-documenting…” and sure enough, I can sort of guess at the function name, and maybe there’s a method that’s obviously removing an object from a list. But I can’t even figure out the larger structure. Someone’s going to instantiate this object, and then call the method, but who? And when? And why? And what’s the intended lifetime scope of this object?
Bugs rarely happen in single methods – 95% of typos and other goofy issues get sorted out before you drop it into QA’s hands. The really impossible bugs are the ones that emerge as side effects of complex, concurrent systems. And a nice succinct sentence here or there describing your thoughts of how these objects work together to solve a problem goes a long way; if I am debugging your code and I find there’s a case where the objects are not working as you intended by your comments, that gives me a very good clue as to where I should look.
When I’m writing software, I first write comments describing the classes and their interfaces, then I’ll write tests, and finally I’ll write the classes themselves. I’m always conscientious about the poor SOB who will one day have to maintain my code.
