[HN Gopher] Comments Are a Code Smell (2019)
       ___________________________________________________________________
        
       Comments Are a Code Smell (2019)
        
       Author : kugurerdem
       Score  : 11 points
       Date   : 2025-03-15 21:07 UTC (1 hours ago)
        
 (HTM) web link (www.aarongreenwald.com)
 (TXT) w3m dump (www.aarongreenwald.com)
        
       | taylodl wrote:
       | _> Well, I dunno. I think the smell was there before you wrote
       | the comments. The comments are febreze._
       | 
       | Awesome! I will never look at comments the same again!
        
       | cjs_ac wrote:
       | The assertion that comments are a code smell assumes that the
       | source of complexity in your codebase is either developer taste
       | or some computer-sciency problem that becomes apparent to anyone
       | reading the code in a few minutes or so. But sometimes the
       | complexity is intrinsic to the problem you're solving; sometimes
       | there's some quirk or edge case that means you can't do the
       | obvious thing. In those circumstances, you need comments to
       | explain what you're doing, how you're doing it, and why.
        
         | kugurerdem wrote:
         | Exactly. I use comments either when some inherent complexity is
         | at play or when I've written seemingly weird code and need to
         | make it easier for myself and others to understand why it's
         | hacky.
         | 
         | I generally try to avoid the latter case, but sometimes,
         | especially when I can't afford to refactor, I just do it, and
         | in such cases having comments is just better than having
         | nothing.
        
       | rhelz wrote:
       | The code tells what the program actually does.
       | 
       | The comments tell what the program _should_ do.
       | 
       | This distinction is so important that English marks it
       | syntactically. Here's an example of how this shakes out:
       | 
       | BAD: // this routine takes its input, multiplies it by 9/5, and
       | then adds 32
       | 
       | Good // this routine converts Celsius to Fahrenheit
       | 
       | Another example: is this code buggy? for(i=0;i<=10;i++) { // do
       | something }
       | 
       | No way to know if you don't know the programmer's intensions,
       | which is to say, if you don't know what the code _should_ do.
        
         | cbeach wrote:
         | You could comment "this routine converts Celsius to Fahrenheit"
         | 
         | Or your could just name the method "celsiusToFahrenheit"
         | 
         | In this example, I'd rather the comment didn't exist and the
         | method was named appropriately.
         | 
         | That said, there is definitely a place for comments in code,
         | especially for explaining the business context behind a
         | counter-intuitive implementation decision.
        
       ___________________________________________________________________
       (page generated 2025-03-15 23:01 UTC)