5 ms·
Ok, I'll be the curmudgeon here. In recent software development efforts I have run, I have put for the rule that "All comments are bugs". Comments get separat
by wglb 15y ago
Ok, I'll be the curmudgeon here.
In recent software development efforts I have run, I have put for the rule that "All comments are bugs". Comments get separated from the code, make statements about obsolete activities, and often mislead the reader, and even sometimes the author.
In place of comments, write code that is as self-explanatory as possible.
I refer to Martin Fowler's "Refactoring" as a way of trying to increase my authority in the matter.
However, I do back off from this extreme position and put comments on individual methods. Sometimes. What helps is using longer method/function/attribute/variable names than pg or tptacek would.
I think the TomDoc example is particularly poorly chosen for the author's thesis, as, more often than not, one is likely to just do "text * num_duplications" inline, no? So why is this even a separate method? Certainly not to save lines of code.
As noted in other comments to this submission, the real value of comments is the why of doing something unusual, not what.
And who was it that said that the Ruby community should spend more time on documentation rather than tools for documentation? A case in point is the doc for EventMachine. This is an insanely useful tool, yet every time I look for the answer to a question about how it operates, the auto-generated documentation leaves me disappointed.
If you are going to spend time on documentation, there is the place to spend it. Make your code readable in its own right.
- gruseom 15y agoI find your comment valuable and largely agree, but it spurred me to write out an objection I have to a common view (not necessarily yours). What helps is using longer method/function/attribute/variable names Sounds great, so why don't all good programmers do that? This is a deeper question than it seems. Over time, I've come to mostly prefer short names. The reason is that longer names add lexical noise to the code; they distort its structure and thus drown out other important information. The lexical is only one of several semantic channels and there are tradeoffs between them: you can't optimize clarity via verbosity. After a certain point (rather quickly, in fact) inflating the code detracts from clarity overall. It's easy to miss this because one often is making X more readable by giving it longer names or spelling its logic out in detail. The trouble is that other things than X have now become more obscure. The question is, what maximizes the clarity of the program as a whole? I'm pretty sure my code would evoke howls from the "all code must be immediately readable [to me]" brigade. I used to feel the same way, but now I don't. It leads to sacrificing deeper comprehensibility (of the entire program) for superficial readability (line-by-line). Maximizing the overall clarity of a system is closely tied to distilling its parts, and the connections between them, to their minima. Code inflation inhibits this. The demand for immediate readability comes from a belief that all code should reveal its secrets immediately. That would be great, except it's impossible. There's a fundamental complexity tradeoff at work. If you opt for verbose readability, you end up with code that is line-clear (I know this function is saving a record to a database or whatever) but system-incoherent (why the hell is it going to the database here?) Talented programmers who care about readability but have a superficial view of what that is end up producing systems with far too much code. They accrete code, which may be impeccably pseudo-readable, when what they ought to be doing is distilling it. Such code is like the old joke about the person lost in a hot air balloon who calls down and says "where am I?", but the guy they're talking to is a technical person who answers, "you're in a balloon twenty feet above the ground". Programs that are built for global intelligibility usually have much less code, but not necessarily the sort you can scroll to and immediately grok. You have to work to begin to understand the program, but once you absorb its conventions understanding proceeds much more rapidly. Latency is worse this way, but bandwidth is orders of magnitude better. The reader I feel responsible to is the one who is willing to put in this work. After all, they're going to have to do it anyway to get anywhere nontrivial.
- 6ren 15y agoWhat do you think of short methods?
- wglb 15y agoA friend of mine who was a smalltalk programmer for 17 years told me that the median length of his methods over his career was four lines. I think that this is admirable and wish my code were more like that.
- 6ren 15y agoIt seems that having many small methods trades one complexity for another. For methods that are only used once and sequentially, it seems to me that it's easier to follow if they are all inlined (by the programmer). If the methods can be reused elsewhere, it's a different matter. On the other hand, methods are modules, giving syntactic and compiler-supported semantic separation - and you can do things like return early. I can't tell which is better. Some people claim that short is better, but it always comes across as a bit rabidly dogmatic, because... well... it's without evidence. There is so much of that in comp sci: design patterns, functional programming, editor and language choice. Most people giving opinions don't even mention what type of task that advice is relevant for, nor give their experience that supports their choice. (It's easy to argue for a choice - smart people unfortunately can argue convincingly for anything.) I tend to use separate methods only if they are reusable (otherwise it's a waste of time making them reusable). I often think of better ways of doing things, so I don't like to invest too much in what I have now. I'm mostly writing prototype code for new kinds of products, not "production code", not for clients, and no one sees it but me. Much code I've seen that it made of many methods and classes looks horribly over-engineered to me, especially when the problem itself is actually very simple if you approach it in the right way. I'd love to hear gruseom's opinion tho.
- gruseom 15y agoI wrote my thoughts up above, but will respond to this here. I agree, both about the short methods school and about programming dogmas in general. I went through a couple years of working in the OO short method style. Recently an old client called me back to help modify some code I'd done for them in 2004, so I went down for an afternoon to help them out. I was really embarrassed. It was obvious to me that I had strung things together in endless chains of delegation (tiny classes and short methods) not because that was simple but because it, at the time, was my belief about programming. I got that belief from other programmers I admired. The truth is that this is how most of us work all the time. I don't mean short methods; I mean picking a style based on our beliefs -- mostly for emotional reasons -- and then seeing the entire programming world through that filter. To be able to just see the problem is difficult when you're operating from one of these positions. Much (most?) of what we do in software development is add extrinsic complexity, which is bad when the problems themselves are hard to begin with. My experience is that your moment of "the problem itself is actually very simple if you approach it in the right way" does eventually come, if you make getting there a high priority. But it's challenging. Most of the time we don't even know what our assumptions and beliefs are, let alone have the flexibility to adapt them to the problem. It's usually the other way around: we adapt the problem to our beliefs because they determine how we even see the problem in the first place.
- spc476 15y agoI would change "All comments are bugs" to "All comments document bugs we have to work around." Otherwise, some maintenance programmer is going to wonder why, only for Solaris, I use poll() on a single file descriptor when I immediately call recvfrom(). With a comment, I can inform said maintenance programmer that under Solaris, the observed behavior is that recvfrom() is NOT a pthread cancellation point, but poll() is, whereas under Linux, revcfrom() IS a pthread cancellation point. In reading over the comments I've written, a majority of them document the various methods of working around bugs on third party components we can't fix. Ah, the joys of working with proprietary, non-source libraries.
- wglb 15y agoAnd this sounds more like the why kind of comment rather than the what, which approach I agree with. That is, you are commenting the pieces of code that a reader would say "er, the heck?" with explanation.