Comments being for why or what is not really important imo, having strong feelings about this probably hurts more than it does good.
The goal is for someone else (or you) to understand what's going on at a point in the future, you include what is needed to achieve that goal. Whether that's what or why or something else doesn't really matter. Sometimes you don't know how much you have to include, but experience and asking colleagues will help you get a better idea.
Do you really prefer digging through years of commit messages to find why a particular line exists? It's a very impractical place for those. And good luck finding the origin of that line if there was an extensive refactor in between.
Also, how do you notify a later viewer that there's a "why" they should check? A comment that says "check commit messages for this line"? :)
Not to mention: you're losing the notes as soon as you move repositories, or worse, version control systems. Yes, I've hit the "SVN git migrate" wall way too many times. For that reason I even started leaving issue numbers in comments for when it's particularly important, in case we lose the commit<->ticket link down the line.
Typically, it isn't digging. It's the last commit, maybe the one before it, and I have tools for doing this (e.g., magit, fugitive).
I don't notify anyone, nor do I need to. When I encounter a WTF moment, I look at the commit messages. When there's nothing there, I curse the last developer.
I guess it can be fun spelunking through commit messages, though, to see when the comment was added and if it still applies.
LOL. I'm going to explain this for myself and then never look at this cursed thread again.
What is important is to clearly communicate the intent of code to the next developer (incl., yourself) who comes across it. Comments are one tool provided to do this. I write comments. I approve pull requests containing comments. But comments are not the only tool, and they're not the best one.
Now most of the time there's no particular difficulty establishing the intent of code. Sometimes, though, there's something weird, something that looks "wrong" but isn't. In those cases, I isolate the weird change using abstractions (at least a variable, but probably a function, a method, a class); I name it and any components well -- long, descriptive, using appropriate conventions; I put automated tests around it, which will fail if anyone changes it without understanding it, providing helpful and explicit error messages (where tools allow); and I write a developed, full explanation in a commit message (which IME will not be too hard to track down, if you've isolated the "weird" change using an abstraction).
That will almost always communicate the the intent. If it doesn't, I (reluctantly) comment it up.
.... sometimes, yeah. When "why" is highly temporal, it's a great fit, since that doesn't often have anything to do with the code or behavior itself - put that in the commit message, and/or in your ticketing system. It's a waste of space and a distraction / source of confusion in code.
For many other things though, it's so easy to "cover up" commit history. Changing how you indent things (or splay one line into multiple), correcting a spelling error, etc all make it dramatically harder to follow than an in-code comment, even with good tool support (which is usually mediocre at best). Of course, you can keep those changes separate, and add them to an "ignore these commits" list for git... but few teams are capable of maintaining that in the long run.
(I assume/hope you just got downvoted in a burst of emotional bikeshedding. certainly doesn't seem negative-reputation-worthy to me)
Until a few years later when you have to move the source code to a new repository or totally different source code control system and lose all the commit messages. In theory there should be a way to migrate the entire tree and keep the commit history but in practice from what I've seen that seldom happens.
Great post. A key point you don't bring up is the aftermath, even if you do deliver. Especially in non-tech companies there still remains the tendency to view these projects as "done" after the end of the project/MVP etc., with no understanding that sites need ongoing maintenance and improvements. And that this work is still considerable.
Agreed, especially for MVPs and "phase 1" projects.
At my current company, it's reached a point where we flat out reject product proposals for features or changes that would need to be hacked together for an MVP without a time commitment from all necessary stakeholders on how it will properly be implemented for phase two (iff phase one is a success). It's amazing how quickly "critical" features become irrelevant to product when they understand even half the amount of work required to properly implement them.
That reminds me of that scene in the series Chernobyl where the main scientist briefs everyone on the cleanup effort and ends with something like "The first battle is won and now begins the long war" with everyone being suitably cold in their response.
I get the same response sometimes when I talk about the long tail of maintenance at work.
I can see this being really useful on documentation sites, kudos.
If you want to make money from your coding knowledge, CourseMaker [1] has similar functionality with video hosting/payments/custom domains all baked in.
You can build your own site like this with CourseMaker[1] (disclaimer: I'm the founder). We don't have SQL support yet, but you can create interactive exercises with JS, Python, Go, Rust, C# and Java.
I learned to code through these kinds of sites (codeacademy and code school especially), I think being able to tinker in the browser with no setup is great.
