4 ms·

I'd like you to offer some examples of code that successfully documents its own raison d'être - in a way that a comment couldn't do better - instead of repeatin

I'd like you to offer some examples of code that successfully documents its own raison d'être - in a way that a comment couldn't do better - instead of repeating this 'crutch of poor developers' rhetoric. I mean, I can write self documenting code without any comments, and it's perfectly understandable. before_create :auto_increment def auto_increment self.count + 1 end That code fails to tell the programmer why it's in the application logic and not defined in the database schema. What should I do instead, so I can code without crutches? def auto_increment_natural_key self.count + 1 end That's not a great deal better, it's still just saying what it does, not why it's there in the first place. def auto_increment_natural_key_because_another_app_relies_on_it self.count + 1 end Is that it?

eru 14y ago
Thanks for trying! Now we just put the comment in the variable name. The compiler just checks the variable names all match up, but doesn't check whether their names make sense. Perhaps the example chosen was too much of a toy to yield valuable insight?
run4yourlives 14y ago
def auto_increment_natural_key_here_because_if_a_product_doesnt_have_a_key_assigned_because_it_came_back_from_return_and_wasnt_assigned_on_during_the_recieve_shipment_process_the_key_doesnt_exist_and_another_app_relies_on_it Pretty sure that's it.
- rhizome 14y ago
  Your sarcasm is screwing with HN's page formatting.
  - dredmorbius 14y ago
    This is what element inspectors/editors are for. Snip, snip.
    - mkopinsky 14y ago
      I had to use inspector to make the page readable, but it's a PITA. GP is a jerk.
      - dredmorbius 14y ago
        Agreed. Just pointing out there's a workaround.
huggyface 14y ago
That code fails to tell the programmer why it's in the application logic and not defined in the database schema Why isn't it a GUID? Why is it 32 bits instead of 64? Why is it signed yet starts at 1? Why isn't it a string? How will the identities be merged? The notion that answering one single question provides clarity is ridiculous.
randomdata 14y ago
Your code doesn't actually seem to do anything, so a comment would either be contradictory to the code, which is confusing, or explain why your code does nothing, which is silly. I would argue that in this case, it is far better to just understand the code and then fix it appropriately. A comment would leave you second guessing. def auto_increment self.count += 1 end (though, for the purposes of self documenting code, count probably is not a great variable name either)
- FuzzyDunlop 14y ago
  Rather ironically, it appears my poor choice of example could have done with some more documentation.
  - randomdata 14y ago
    I'm now curious to know what you would have written for documentation. Though, I think your example turned out to be a great one because it highlights that not everyone reads code the same way. Personally, I load large segments of code into memory and then mentally step through. You left me wanting more to see the context in which the method was to be executed, but I didn't really feel the need for comments. However, with just the one method that you wrote in your example, that seems to indicate that you read just one function at a time. If you are not observing the code as whole, I guess a comment would help. I often find them taxing though, as they have to be read into memory as well. I think that discrepancy is why the comments vs. self-documenting code debate exists.
    - FuzzyDunlop 14y ago
      The problem was I initially hinted at the context in my first example, with a call to Rails' `before_create` callback method. I then omitted it from every other example, thinking it'd be inferred. Evidently that wasn't very clear. But the way in which people read code is an interesting point, which I actually think might be worthy of its own discussion. Looking at the psychology behind this would be good, I think.

eru 14y ago

Thanks for trying! Now we just put the comment in the variable name. The compiler just checks the variable names all match up, but doesn't check whether their names make sense. Perhaps the example chosen was too much of a toy to yield valuable insight?

run4yourlives 14y ago

def auto_increment_natural_key_here_because_if_a_product_doesnt_have_a_key_assigned_because_it_came_back_from_return_and_wasnt_assigned_on_during_the_recieve_shipment_process_the_key_doesnt_exist_and_another_app_relies_on_it Pretty sure that's it.

rhizome 14y ago
Your sarcasm is screwing with HN's page formatting.
- dredmorbius 14y ago
  This is what element inspectors/editors are for. Snip, snip.
  - mkopinsky 14y ago
    I had to use inspector to make the page readable, but it's a PITA. GP is a jerk.
    - dredmorbius 14y ago
      Agreed. Just pointing out there's a workaround.

huggyface 14y ago

That code fails to tell the programmer why it's in the application logic and not defined in the database schema Why isn't it a GUID? Why is it 32 bits instead of 64? Why is it signed yet starts at 1? Why isn't it a string? How will the identities be merged? The notion that answering one single question provides clarity is ridiculous.

randomdata 14y ago

Your code doesn't actually seem to do anything, so a comment would either be contradictory to the code, which is confusing, or explain why your code does nothing, which is silly. I would argue that in this case, it is far better to just understand the code and then fix it appropriately. A comment would leave you second guessing. def auto_increment self.count += 1 end (though, for the purposes of self documenting code, count probably is not a great variable name either)

FuzzyDunlop 14y ago
Rather ironically, it appears my poor choice of example could have done with some more documentation.
- randomdata 14y ago
  I'm now curious to know what you would have written for documentation. Though, I think your example turned out to be a great one because it highlights that not everyone reads code the same way. Personally, I load large segments of code into memory and then mentally step through. You left me wanting more to see the context in which the method was to be executed, but I didn't really feel the need for comments. However, with just the one method that you wrote in your example, that seems to indicate that you read just one function at a time. If you are not observing the code as whole, I guess a comment would help. I often find them taxing though, as they have to be read into memory as well. I think that discrepancy is why the comments vs. self-documenting code debate exists.
  - FuzzyDunlop 14y ago
    The problem was I initially hinted at the context in my first example, with a call to Rails' `before_create` callback method. I then omitted it from every other example, thinking it'd be inferred. Evidently that wasn't very clear. But the way in which people read code is an interesting point, which I actually think might be worthy of its own discussion. Looking at the psychology behind this would be good, I think.