5 ms·

This comment was originally posted by shasty ut for some reason has since been deaded. I thought it was worth reposting: Over commenting is a bad practice. Com

• anigbrowl 14y ago
  Forcing a developer to constantly shift between the english language and a programming language takes up precious screen space and insults the developer by constantly making her switch gears. What nonsense. In this age of syntax highlighting it's easy to make comments vanish in an editor; there's no shortage of screen space anyway; and if you find it insulting to have a guide to the function of the code, then maybe you're a little thin-skinned. Code is there to be maintained, not to serve as your mental gymnasium. It's a means to an end. Many skilled programmers may do fine without comments, but the above basically sounds like an excuse for not writing any.
• robomartin 14y ago
  I disagree. This isn't about interfaces. This is about their inner workings and the reasoning behind some of the decisions or techniques being made. You talk about over-commenting. I am talking about no comments whatsoever, not even to document methods or subroutines. I cloned this one project that was loaded with methods not used anywhere. In fact, it had included the SBJson framework and it was being used in a method that never got called. The issue came up because it collided with my own use of SBJson on my project and I wanted to figure out what to do about it. It turns out that I could just delete the entire thing and it did not affect the code at all. I'll give you another example. I have not programmed in Forth in a long time. Maybe fifteen years. However, I do have tons of Forth code that I wrote back then for various projects. All of it is very well documented. I have no doubt that, fifteen years later, I could grab that code and be back in the swing of things in no time at all. I wouldn't have to read through the code in detail and go through the process of building stack images in my head to figure out what is going on. Without comments code libraries like that become impenetrable black boxes. I could say the same about LISP. I haven't touched it in ages. I wrote tons of utilities and at least one major framework (one year dev time) for a variant called AutoLISP (runs inside AutoCAD). Again, tons of comments which would allow me to jump right in and know exactly what is going on. It should go without saying that trivial stuff does not require comments. As an hypothetical example, a loop that searches an array (or whatever) for a specific match doesn't need line-by-line comments. What I might do here is, again, hypothetical, just before the "for" statement throw-in a comment that says something like "Look for CRC code match in packet data". With that simple line anyone reading the code knows what the intent was. I can read that code five years later and know exactly what it does without having to read backwards and forwards through the code to figure out what each variable might be, where they come from, what they are loaded with, what the intent might be, etc. I also find it invaluable to document state machines (particularly for hardware --FPGA-- designs). If you take something like a custom DDR3 SDRAM controller state machine, well, it isn't a trivial thing to read through and figure out what it is doing. Well-authored comments can turn something that would take hours-upon-hours to comprehend into an easy read. I have seen the value of good comments and code documentation many times over during my career. Keep in mind that I am not making a comparison between sparse comments and writing a book.
  • sirmarksalot 14y ago
    How about you break out your "Look for CRC code match in packet data" loop into a boolean function called "PacketContainsCRCCode"? The rule of thumb that I learned early on, and that I try to apply, is that comments should answer the question "why," not "what." "What" is easily answered by naming your methods (and variables, should you be forced to use them). I know what you're getting at. There's nothing worse than reading a 50-line function with no comments. But the real WTF isn't the lack of comments - it's having a 50-line function in the first place (or 8000 lines for that matter). Having lots of comments is a code smell - it indicates poorly factored code. Next time you need to write a comment explaining what a piece of code is doing, try writing a function instead, with a name that says what it's doing, and see where that takes you. I highly recommend Misko Hevery's "Clean Code Talks" on YouTube. They're part of the Google Tech Talks series, and they will blow your mind if you let them.