Coding without comments and the ‘Single Use’ Principle


So it's all the rage to talk about how comments are bad to use, bad to rely on, and should only be used to describe why something is being not done, not how. And for the most part I agree. As soon as a comment is written it becomes stale. It's hard enough to get the time to update the code, much less updating the comment. With today's integrated development environments with name completion and the like, there is no excuse for using abbreviated variable or function names in your code. This is not to say that variable names should go on forever, they should be as long as they need to be to express their purpose and NO LONGER!

 'Fair nuff, no real problems here. Now, the Single Use Principle states that some “thing” should have exactly One purpose.  This “thing” is either an object, class, function, some item of encapsulation.

Again, who can argue with that, makes sense.

Now, my annoyance 🙂 (c'mon you knew it was coming) So ok, we have these functions which end up being relatively small and easy to read as we've emplopyed single use and descriptive variable/function names this is a good thing. The downside is, you now have class files with many many many small functions and getting a big picture view of what is actually happening becomes impossible… Instead of spending all your time figuring out what code does, you end up diagramming the call mapping of your functions so you can find out what is really being called, in what order. All these small almost atomic functions become more time wasting to follow then before we employed our “Best Practices” …

 Very disappointing folks. Got a good solution? Neither do I, but I suspect it comes in the form of more advances to the development environment. I would love to see expandable function calls in code so a simple expand click would show you whats actually going on without having to diagram it all out. I know visual studio has a code declaration window which is great but not quite what the doctor ordered.

At any rate, the best practices are worth it, but let's not pretend they aren't causing another, and perhaps larger, maintenance issue.