4 ms·

Code involves names of methods and variables which can greatly aid in understanding as well. I've always maintained that comments should only be in code to expl

Code involves names of methods and variables which can greatly aid in understanding as well. I've always maintained that comments should only be in code to explain something that is not obvious. If you're calling the SaveUser function and passing in a new User object that you had just created, a comment of "Save the new User object" adds nothing but noise.

krylon 5y ago
A comment like "This method opens a separate database connection so as not to mess with the ongoing transaction" or some such would be rather helpful, though.
- jaywalk 5y ago
  Within the code I write, I can't think of a scenario where that wouldn't be obvious. But if it is indeed not obvious, then I agree that would be a helpful comment.
  - krylon 5y ago
    I guess that was what I was trying to say. Make your code as obvious as possible, and use comments to explain what's not obvious. Although people have vastly different ideas of what is or isn't obvious.
  - ziml77 5y ago
    What's obvious now might not be obvious later or to another person.
aequitas 5y ago
Most code (and the effects of removing/refactoring it) are not that obvious at first glance. But I agree, if your code is as simple and self documenting as that a comment like that doesn't add anything. But a lot of the intention cannot be expressed in code alone. This is where comments help enormously. It allows me to review the code and compare it to the writers (often me) intent and spot bugs or refactor if needed. Without it a lot of knowledge has to be rediscovered again.
pjerem 5y ago
- Do you SaveUser to the database directly or do I have to somehow call something to validate the transaction ? - Once it’s saved, can I continue to use my User model or should I fetch the more complete one from the database ? - Does this even SaveUser to the database or on a temporary structure that will be fetched by our UserCreationBot ? - Does SaveUser checks if the username already exists or should I check myself before calling it ? - Does SaveUser checks that current user is allowed to create new users or should I check it before ? - What happens if SaveUser is called with a User with an empty password ? Does it means that the input is wrong or am I legitimately creating a user that can’t login?
- jaywalk 5y ago
  Check the code of the SaveUser method.

krylon 5y ago

A comment like "This method opens a separate database connection so as not to mess with the ongoing transaction" or some such would be rather helpful, though.

jaywalk 5y ago
Within the code I write, I can't think of a scenario where that wouldn't be obvious. But if it is indeed not obvious, then I agree that would be a helpful comment.
- krylon 5y ago
  I guess that was what I was trying to say. Make your code as obvious as possible, and use comments to explain what's not obvious. Although people have vastly different ideas of what is or isn't obvious.
- ziml77 5y ago
  What's obvious now might not be obvious later or to another person.

aequitas 5y ago

Most code (and the effects of removing/refactoring it) are not that obvious at first glance. But I agree, if your code is as simple and self documenting as that a comment like that doesn't add anything. But a lot of the intention cannot be expressed in code alone. This is where comments help enormously. It allows me to review the code and compare it to the writers (often me) intent and spot bugs or refactor if needed. Without it a lot of knowledge has to be rediscovered again.

pjerem 5y ago

- Do you SaveUser to the database directly or do I have to somehow call something to validate the transaction ? - Once it’s saved, can I continue to use my User model or should I fetch the more complete one from the database ? - Does this even SaveUser to the database or on a temporary structure that will be fetched by our UserCreationBot ? - Does SaveUser checks if the username already exists or should I check myself before calling it ? - Does SaveUser checks that current user is allowed to create new users or should I check it before ? - What happens if SaveUser is called with a User with an empty password ? Does it means that the input is wrong or am I legitimately creating a user that can’t login?

jaywalk 5y ago
Check the code of the SaveUser method.