3 ms·

You also get what is changing by doing "git diff", and often, it is self explanatory, especially if you have already commented in code why you did what you did.

by GuB-42 3y ago

You also get what is changing by doing "git diff", and often, it is self explanatory, especially if you have already commented in code why you did what you did. For example: - code: MAX_SIZE=1024 // maximum size the backend supports - commit: limit the size to 1024, as it is the maximum the backend supports - jira: fixed the problem by limiting the size to 1024, as it is the maximum the backend supports - confluence: do not exceed 1024, as it is the maximum size the backend supports - standup: I set the maximum size to 1024, as it is the maximum the backend supports - release note: Maximum size set to 1024, as it is the maximum the backend supports This is all redundant. I used a simple example for the sake of brevity, and one-liners are reasonable in every case, but the problem is when you are expected to write a wall of text every time, when in reality, there is everything you need in the code.

kelnos 3y ago
I'm generally wary of code comments. They tend to rot; people change the code around them but then forget to update the comments. They also take up valuable screen real estate. I'd mostly rather be reading code than comments, and I can see more context when there are fewer comments. If a comment truly is necessary, it should explain why the code is doing something tricky, unusual, or unexpected. In your particular example, that comment is superfluous; the constant should just be called MAX_SUPPORTED_SIZE, or something similar, that describes it better and makes the comment redundant and unnecessary. Otherwise I agree; there's so much redundancy in our work, it's silly...
- fusslo 3y ago
  As someone who's been 'the next guy' to people who share your opinion: I really disagree with your opinion
- GuB-42 3y ago
  I am generally on the same opinion as you are. I dislike superfluous comments and documentation. In fact, I usually try not to read these as these can be deceiving. But this is one of the few cases where I think comments are worthwhile. That is, as an out-of-band channel where you explain things that are not in the code base, that is not common knowledge to skilled programmers, and that is hard to express in other ways. This is a simplified example, normally, one would say more than that. Something like "for historical reasons, the backend is configured with a size limit of 1024, larger messages may be dropped". This value may be the result of a conversation with someone from the backend team, and without this comment, a newcomer will have absolutely no idea about the why, even if his is a programming god. And there is no easy way to express that in code. "MAX_SUPPORTED_SIZE" without any context may be insufficient, as it may raise questions about why this limitation even though the software used for the backend shouldn't have this limit. I don't think the value of comments is only on the trickiness of the code. Some code like bit twiddling hacks may be tricky, but these are the kind of things good programmers should know, or if they don't, learn. There are publicly available resources for that. But parts, even simple parts, that require domain knowledge, or worse, knowing specific people in the company definitely benefit from comments if code can't express it.

by GuB-42 3y ago

kelnos 3y ago

I'm generally wary of code comments. They tend to rot; people change the code around them but then forget to update the comments. They also take up valuable screen real estate. I'd mostly rather be reading code than comments, and I can see more context when there are fewer comments. If a comment truly is necessary, it should explain why the code is doing something tricky, unusual, or unexpected. In your particular example, that comment is superfluous; the constant should just be called MAX_SUPPORTED_SIZE, or something similar, that describes it better and makes the comment redundant and unnecessary. Otherwise I agree; there's so much redundancy in our work, it's silly...

fusslo 3y ago
As someone who's been 'the next guy' to people who share your opinion: I really disagree with your opinion
GuB-42 3y ago
I am generally on the same opinion as you are. I dislike superfluous comments and documentation. In fact, I usually try not to read these as these can be deceiving. But this is one of the few cases where I think comments are worthwhile. That is, as an out-of-band channel where you explain things that are not in the code base, that is not common knowledge to skilled programmers, and that is hard to express in other ways. This is a simplified example, normally, one would say more than that. Something like "for historical reasons, the backend is configured with a size limit of 1024, larger messages may be dropped". This value may be the result of a conversation with someone from the backend team, and without this comment, a newcomer will have absolutely no idea about the why, even if his is a programming god. And there is no easy way to express that in code. "MAX_SUPPORTED_SIZE" without any context may be insufficient, as it may raise questions about why this limitation even though the software used for the backend shouldn't have this limit. I don't think the value of comments is only on the trickiness of the code. Some code like bit twiddling hacks may be tricky, but these are the kind of things good programmers should know, or if they don't, learn. There are publicly available resources for that. But parts, even simple parts, that require domain knowledge, or worse, knowing specific people in the company definitely benefit from comments if code can't express it.