Comments are for things that are __impossible__ to tell from the code and the code alone.
Comments are subjective, code isn't.
90% of the companies I've worked at have had commits linked to actual tickets in a ticketing system. if i really need to understand what was going on, holistically, i could just git blame and go there. i look at tests, I look at the discussion around the code between the person who reviewed the PR and the person who raised the PR. Too often people use comment incorrectly or noisily.
No one is saying you shouldn't write comments. People are saying there are way better practices out there and you should really ask your self, why you are writing a comment to begin with and is there a better way to capture what it is your are trying to do so product managers, developers, engineering managers, QA people understand what the intent of that commit was.
>why you are writing a comment to begin with and is there a better way to capture what it is your are trying to do so product managers, developers, engineering managers, QA people understand what the intent of that commit was.
So first of all, not everyone works with massive teams. I work in a three person team with two of us actually doing the coding, and really it's 90% myself.
Comments are generally put in to explain in very simple terms what the function is doing, so when we have to go back or we are upgrading functionality it's easy to remember. Second, comments are put into specific parts of functions to explain how/why something was done if it's not blatantly obvious. So later on when we are going back and don't remember exactly why it was done that way, we can see if it was done that way because of other specific assumptions.
>No one is saying you shouldn't write comments. People are saying there are way better practices out there
You literally contradict yourself. You are literally saying "there are way better practices out there (than writing comments)". But you also say no one is saying you shouldn't write comments?
And hey- I get we are talking about different workflows.. but that's my point. You are assuming that every commit is linked to a specific ticket in a system with an entire discussion around it. I mean ok, but do you really think that is how small agile teams work? I would get absolutely nothing done if I did that. And the point still remains, even if there are tickets to commits and discussion around it... if you are looking into some random function and wondering why it does X- you are arguing it's better to look into some commit history instead of reading a comment directly there to see why it is how it is? That seems like a bad argument on your part.
> You literally contradict yourself. You are literally saying "there are way better practices out there (than writing comments)". But you also say no one is saying you shouldn't write comments?
Comments used to be a catch all for everything that wasn't code. Comments are still useful, but they are often abused.
Comments are for things that are __impossible__ to tell from the code and the code alone.
Comments are subjective, code isn't.
90% of the companies I've worked at have had commits linked to actual tickets in a ticketing system. if i really need to understand what was going on, holistically, i could just git blame and go there. i look at tests, I look at the discussion around the code between the person who reviewed the PR and the person who raised the PR. Too often people use comment incorrectly or noisily.
No one is saying you shouldn't write comments. People are saying there are way better practices out there and you should really ask your self, why you are writing a comment to begin with and is there a better way to capture what it is your are trying to do so product managers, developers, engineering managers, QA people understand what the intent of that commit was.