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)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.
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.
Actually, I would say your intent there was quite clear, which is where I came to realize that the code did nothing. Without that context, one could assume the method was used for its return value where the code could very well have had purpose as written.
What wasn't clear was how the count attribute was intended to be used throughout the rest of application. In the real world I would start to build a mental model around the uses of count, which was not available from your example. In terms of self-documenting code, I liken a short code snippet like your example to a sentence fragment in english. The entire sentence, or statement if you will, encompasses much more of the codebase.
This is definitely an fascinating topic, but unfortunately one that is very difficult to discuss for many reasons. I wonder how we can dig into the physiology aspects that you raise without the prevalent "my way is the only true way" attitude?
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?
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.
Pretty sure that's it.
I mean, I can write self documenting code without any comments, and it's perfectly understandable.
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? That's not a great deal better, it's still just saying what it does, not why it's there in the first place. Is that it?