5 ms·

Code is for computers to make them do exactly what you want them to do, comments are for your co-workers (and you) to make them understand what you actually mea

Code is for computers to make them do exactly what you want them to do, comments are for your co-workers (and you) to make them understand what you actually meant to achieve.

jaywalk 5y ago
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.
javert 5y ago
I disagree. Code is not just for controlling the computer. Just as importantly, it's also meant to be read by humans. So, code should be written in a way that is easy for a human to read and understand. Code should easily and naturally show what it's intended to achieve 99% of the time. Comments should be used sparsely, and only to express things that must be expressed and cannot be expressed in code.
bregma 5y ago
All code is literature intended exclusively for humans. Computers read machine instructions; they're incapable of reading code. Know your audience.
- jbay808 5y ago
  Humans wouldn't care so much about semicolons, but I do want the compiler to understand my code, too.
  - hawski 5y ago
    Have you seen decompiled code? That's all that compiler cares about, it is not pretty.
- teknopaul 5y ago
  nonsense. code is intended for a computer by definition.
  - pjerem 5y ago
    No. Code is intended for your teammates. Compiled machine code is for your computer. If you were addressing a machine, you would be writing 0s and 1s, because o boy do the machine know how to execute those little ons & offs.
    - retsibsi 5y ago
      People often insist on this point, and I still don't get it. Honestly it comes across as intentionally exaggerating a claim beyond reason, in order to make it sufficiently counterintuitive to sound clever. The point of the program is to get the computer to perform some task; the way we get the program into the computer is to write code. You can say we're writing code for the compiler if you want to be pedantic; or you can say we're writing code for humans too, which is a perfectly valid point. But what do you actually mean by insisting that no, the code isn't for the computer at all, it's solely for other humans? It's clearly the language we use to communicate with the computer to tell it what to do; the fact that there's a translation step (performed by the computer) between what we write and what the computer executes doesn't change that in any relevant way.

Code is for computers to make them do exactly what you want them to do, comments are for your co-workers (and you) to make them understand what you actually meant to achieve.

jaywalk 5y ago

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.

javert 5y ago

I disagree. Code is not just for controlling the computer. Just as importantly, it's also meant to be read by humans. So, code should be written in a way that is easy for a human to read and understand. Code should easily and naturally show what it's intended to achieve 99% of the time. Comments should be used sparsely, and only to express things that must be expressed and cannot be expressed in code.

bregma 5y ago

All code is literature intended exclusively for humans. Computers read machine instructions; they're incapable of reading code. Know your audience.

jbay808 5y ago
Humans wouldn't care so much about semicolons, but I do want the compiler to understand my code, too.
- hawski 5y ago
  Have you seen decompiled code? That's all that compiler cares about, it is not pretty.
teknopaul 5y ago
nonsense. code is intended for a computer by definition.
- pjerem 5y ago
  No. Code is intended for your teammates. Compiled machine code is for your computer. If you were addressing a machine, you would be writing 0s and 1s, because o boy do the machine know how to execute those little ons & offs.
  - retsibsi 5y ago
    People often insist on this point, and I still don't get it. Honestly it comes across as intentionally exaggerating a claim beyond reason, in order to make it sufficiently counterintuitive to sound clever. The point of the program is to get the computer to perform some task; the way we get the program into the computer is to write code. You can say we're writing code for the compiler if you want to be pedantic; or you can say we're writing code for humans too, which is a perfectly valid point. But what do you actually mean by insisting that no, the code isn't for the computer at all, it's solely for other humans? It's clearly the language we use to communicate with the computer to tell it what to do; the fact that there's a translation step (performed by the computer) between what we write and what the computer executes doesn't change that in any relevant way.