Code captures only a portion of the thinking that went into the software's design. If you don't preserve the rest of that thinking elsewhere, you're forcing people to recreate / rediscover it later - and probably the most common way to do that is to throw away the code and rewrite it.
So-called "level of intent" comments as well as comments highlighting tradeoffs, gotchas, flaws, limits, exceptions, assumptions, and so on, are incredibly valuable if you preserve them alongside the code. Comments explaining why this function exists and what it's for can help you quickly come up to speed on a new code base - this is especially helpful when it comes to handing off code to a new owner or expanding the team of owners. The following code may or may not be well written (who can say??) but it's not exactly inviting new contributors: https://github.com/FFmpeg/FFmpeg/blob/master/libavcodec/moti...
Around the time of writing the code, comment-free code looks clear to the author because they have the benefit of all of the thinking that went into writing the code.
I'd argue that in production is when comments are often most valuable. The middle of a crisis is a terrible time to wonder what assumptions were made when writing code a specific way, or if a certain line of code that seems to be doing something weird really is weird or if it was based on something you're not considering. It's also the time when you want to maximize the number of people that can jump in and help.
Everybody has their own coding standards and there is certainly some subjectivity to those standards. Here's mine for people who work for me: if you don't document your code, you have no business touching anything that goes anywhere near production, you can't do anything that is critical path, and you should make a sincere effort to change or start looking for another job. :)
//-----------------
// <date> This is to work around a bug in the third party
// function foo() (filed bug report #foo234). This code does ...
//
// <date six months later> foo() still not fixed.
//
// <date one year later> foo() still broken. Bug report returned as
// WONT-FIX. Sigh.
//-----------------
Not unpopular at all. This is totally sane. I wish more companies cared about good coding practices, code quality, and development life cycle. Things like comments made more sense in an era when there was no version control, no conventions around code style, no testing, etc.
Hey everyone look, we have version control! That means there is no reason to explain anything!
Version control, code style conventions, and testing have nothing to do with explaining how something works or writing about potential pitfalls of this function if some other core logic were to change etc.
Absolutely baffling you guys are arguing for never writing comments.
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 excuses
* They're used to validate the existence of crappy code
* They do nothing for you in production
Instead:
* we commit to writing log messages... which are sort of like comments, but they work in production