//

// Dear maintainer:

//

// Once you are done trying to 'optimize' this routine,

// and have realized what a terrible mistake that was,

// please increment the following counter as a warning

// to the next guy:

//

// total_hours_wasted_here = 42

//

The inverse of this is also useful:

// Dear maintainer,

// The code which follows was hacked together under desperate pressure.

// It's not smart. // It's not doing anything really subtle. // It's the only thing we could get to work in the time.

// If you want to chuck it and replace it, you absolutely should.

Hey, that one I actually can replace with self-documenting code! Oh joy!

It's useful, until you realize you have this on 90% of your code.

That's when a full rebuild can be justified.

I'm doing that atm, but I think my predecessor lacked the humility to admit that his code was bad, which is how it went up to 150K of code that basically concatenates XML, converts it to JSON and concatenates HTML on the front-end from the result.

Not a bad idea.

My code would probably be better served by:

This place is a message… and part of a system of messages… pay attention to it!Sending this message was important to us. We considered ourselves to be a powerful culture.

This place is not a place of honor…no highly esteemed deed is commemorated here… nothing valued is here.

What is here is dangerous and repulsive to us. This message is a warning about danger.

The danger is in a particular location… it increases toward a center… the center of danger is here… of a particular size and shape, and below us.

I refer to this type of problem a lot when arguing comments are useful. No amount of code can document the code that isn’t there for a reason.

Or you can write tests for every single not there case. Just bringing it up, I usually write lots more comments than tests. I also encourage my teammates to add comments. The problem is when one can't really explain why the simpler approach didn't work. That requires more research just to write the comment, but I think it pays off really quick.

Tests are useful, but the big reason that comments are useful is that they are co-located with the relevant code. At the moment, I don't know of any tools that allow you to 1) specify which lines of code are directly relevant to a particular test case, even when the surrounding code changes and 2) see a list of test cases related to the currently highlighted line.

I'm sure it would be possible to build such a tool, but the complexity is quite substantial compared to a simple comment or two. If you really want to go the full-test-coverage route it makes a lot more sense to focus that energy on pure/immutable/statically-verified programming rather than some finicky test cases that add substantial maintenance cost to the code.

> Tests are useful, but the big reason that comments are useful is that they are co-located with the relevant code.

That's a not-often-talked-about (that I see anyway?) thing I really like about rust - I don't get to use it much, but when I do I think having 'doc tests' alongside comments heading a function and 'module tests' at the bottom of the same file is great.

Exactly. And then the question remains: why? Why hate comments so much? I never got that

I would conjecture that it has two components:

1. Ancestral memory of programming in languages like assembly or early Fortran where your code was going to be spaghetti because the language was capable of little else, so it had to be drenched in comments that would be unnecessary in a better language.

2. Overreaction to personal memory of overzealous professors who demanded assignments be drenched in excessive comments.

Related to #2, I'm still recovering from high school AP English. We had to meet quotas for a certain number of underlines / notes written in the margin per page. For the better part of a decade I haven't been able to pick up fiction without the feeling that I'm working through a textbook.

Until the code changes, then the comments are usually worse than nothing

No. Comments are like a parity check. If the comments don't match the code, then you know that either:

1) The comments are correct, but the code is wrong. This is a bug. 2) The comments are wrong, but the code is correct. This is equally a bug. Whoever makes the change has an obligation to describe their changes with a comment.

Code with no comments? Could be right, could be wrong, who knows?

Good luck maintaining that.

I wish I could upvote your comment more, but putting it in my bookmarks will have to do for now.

I've seen this counterpoint brought up many times before, but I'm struggling to think of the last time I experienced it. Is it really a common problem for you?

Yes, the issue isn't that most comments are inaccurate, it's that the inaccurate ones are so costly. When the comment doesn't match the code, it makes you question the code and the intent. 90% of the time, comments are accurate or just redundant (the code is descriptive enough), but that 10% of the time when the comments says A and B is happening, I end up chasing down whoever or digging through changelogs and tickets to find the comment wasn't updated.

For the kind of code comment we started this thread talking about (explaining why some simpler/more obvious process is not used), this seems vanishingly unlikely.

Then you fire the coder who changed the code without updating the comments?

Most code doesn't need comments.

That's a waste. Just train them better.

> The problem is when one can't really explain why the simpler approach didn't work.

Another benifit I have found is that in studying the problem to understand why the simpler approach doesn't work, you find out that it can actually work.

I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. That way I can use as much space as I like for it and the timestamps make it clear that it's historical commentary, not a description of how the code works right now.

Some people advocate putting lots of stuff into commit messages, which makes me think I'm missing something -- commit messages are much less visible/accessible than comments in my workflow, so I don't expect my commit message to be seen.

Do you always read the whole git history of a file before editing it? What interface do you use for that?

An idealistic reason for encouraging longer-form commit messages is that they have the side effect of more coherent commits, making the history easier to navigate, making the history more useful, and so your workflow will probably use the history more.

A practical reason for longer-form commit messages even in modern PR workflows is that they allow you to create and view commentary on a group of changes across files without leaving your editor.

As an interface to git, nothing beats magit. Even if you never use Emacs for editing any text files, it's useful as a magit runner.

VSCode git-lens. Mandatory extension. Either way, I think both are useful, although for documenting weird code I think code comments are more important. I the commit message you should explain why you change the code. In the code, why it works like that.

gitlens is incredible. It passively educates on the git history so you learn about how old each section is and who was mostly behind it or worked with it last without ever requiring dedicated effort since it just sits there at the end of the selected line.

I still wouldn't use git as a replacement for comments since git history is wiped out all the time. Moving files or reformatting or a million other things could remove a critical commit message.

It’s super useful, rarely, when things haven’t moved around or someone wrote a good commit msg.

It’s a dumb idea, because that content gets lost as soon as you move things around.

Counter-point: moving things around in a way which doesn't preserve history is a dumb idea.

Moving/renaming a file? Commit the deletion and insertion together, preferably with no other changes (including to the contents of the file; commit those afterwards). In the best case, VC will treat this as a move and showing the history will include that of the old place/name. In the worst case, that history of file 'foo' will "end" with a commit like 'Rename bar to foo', with a diff showing the content moving from 'bar' to 'foo'; we can continue reading the history by switching to 'bar' if we want.

Moving code from one file to another? Similar story: commit the insertion and removal together; preferably with little/nothing else in that commit; preferably with a commit message explaining the change. This way, the code doesn't appear from nowhere in the commit history: when we look at the commit where it appears, we will also see where it came from before.

Moving a file from one repo to another? Dump that file's history as a patch, apply that patch in the new repo, then clean up (e.g. rename, move, etc. as appropriate). Alternatively, for larger sets of changes, add the old repo as a remote for the new repo, make a branch in the old repo which contains only those parts we want to move, fetch that branch into the new repo and merge it, then remove the remote.

> moving things around in a way which doesn't preserve history is a dumb idea

I don’t disagree with you but you can’t prevent it.

If you use an IntelliJ based IDE you can view commit entries for each line in the gutter.

I prefer comments but yes. If something doesn't make sense, one of my first things to try is to check the `git blame` and see if there's anything recent (or close to when the bug reportedly appeared, such as between two versions). Sometimes the commit message tells me something but usually not, but just looking up the ticket number from the commit message on our issue tracker can be enough hint sometimes. Especially on our SaaS product, if a problem just popped up in Prod and especially if the bug seems both easy to reproduce and feels like "wasn't us" I'll make a quick guess on a 'known good version', try to reproduce and the `git bisect` to find the culprit. Not to blame but just to figure out what's wrong in a very easy way. Sometimes I can fix it easily from that or ping the person who made the boo boo and they will usually know how to fix it quickly.

In the context of regular development? I almost never do any of that.

Not with every file but I have a question as to why something might exist or why it's implemented the way it is or it just doesn't look quite right then I'd absolutely go back and read the commit message that goes with the code - "Blame" feature works well here, I use TortoiseSVN.

The GitHub web interface, specifically the "blame" view for a file.

That only shows the most recent commit, which is IME often not substantive, just some treewide commit like "autoformat" or "moved class into another file" or whatever. I can click on the parent commit button repeatedly until I find all the info but that's really not a good interface for exposing the history of a class.

Each line in the GitHub web blame interface has a little icon which, when you hover over it, says "View blame prior to this change" - I use that all the time.

Yeah that's the parent button I was referring to in my comment.

I use fugitive, which lets me pop open a blame view for code I'm looking at and trace its lineage. It's often helpful, and when the commit messages are good, very helpful.

> I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit.

Having worked with codebases that have switched SCMs and SCM-adjacent issue management systems multiple times without retaining full history, I'd prefer to have the commentary in code even if it is also in those other places.

One caveat with this method is that your source control system evolves and things get archived. Code is around forever but everything around it may change.

10 or 20 years from now your code may still be running, the issue system or the git commit log may not be.

I am fiercely protective of my issue tracker and source history for exactly that reason. I have tools that can grab a full backup should I ever switch to something else: https://datasette.io/tools/github-to-sqlite

I find an issue link only works if e is a good enough comment alongside it (ie. Attempting to eliminate this mutex is bug prone, see <link> for archiyectures and their problems).

I also do this with optimisations, when I work on low-level code:

If I come up with an inefficient algorithm that's short and readable, I tend to optimise it to something better but leave the reference implementation inside a code block.

(This goes without saying, but: I don't leave "commented code", but code inside comment, generally formatted with Markdown)

Sounds like a good use case for property testing!

Is there a reason you don't leave a comment with the commit hash of the change instead?

Some day in the distant future someone will only have a tarball of the source of the last version that worked; if they're lucky.

Save that poor sod; have your comments live in your code, not in an SCM system for your code.

GPL has this idea in it: trying to define what exactly should go into that tarball. The question seems meaningful and important even for proprietary code. If some authors assume that anybody modifying their code should be able to look at git commits, that probably simply means that "the preferred form of the work for making modifications to it" is a git repo.

Yes, text is better for convenience and for being future-proof. It's like leaving a description of the bug I'm fixing, instead of just a JIRA ticket identifier.

not relevant: I often left comments that helped to explain my situation. One of my last comments:

> Resignation letter sent

Sometimes code is the only way to love and to talk with...

Edited: fix some typo errors

>Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason.

>So now I have a new rule: every time I try a simple approach and it fails and I replace it with a more complicated one that works, I add a comment explaining the previous strategy and why it didn't work.

My strategy is to comment out the failed attempt and leave it there for next time.

I use a design doc for this in the style of a append journal. I made this decision a/e/i/o/u based on this and that. the why and the why not. Then I keep appending. easy reference.

If you have a unit test for that piece of code then that would probably help to act as a stopgap measure against attempting to "fix" the complicated-seeming code.

I mean sort of. If the goal of leaving the a comment about the approach that didn't work is to save somebody time before they try that approach again, a regression test is essentially asking the next developer to reconstruct a broken algorithm from thin air based a test. In my opinion, that's close to impossible. So the best case scenario is they re-implement the bad approach and it fails a test. They still wasted a bunch of time that could have been prevented with a simple comment.

Unit tests have a much bigger chance of being seen as well. There have been a few times where I will write unit tests that don't really test something is working but just check if it has changed. For example there is one table where every time you add or remove a column, you have to make a considered change to another section of the code.

Rather than adding a comment saying "hey make sure you change that other section" I have test which lists the columns in the table and fails if they change. Then the person who changed it will see the comment on the test explaining why it failed and what they must do.