Hacker News Reader

Great thing about Git, is you can look at the code at the time when the comment was written, and still retain the original value of the comment.

If there have been major structural changes that make the comment useless- that’d be pretty easy to see, it’s very easy to delete comments

This, I prefer an inconsistent comment that can still shred light on some code than no comment at all. Code also becomes obsolete and no comment just makes it worse.

Comments in code are like pizza or sex. When they are good, it’s really good. When it’s bad, it’s better than nothing

But then are you looking at the git context of all the comments you come across ?

I'd argue you could do the same on methods and class you want more context on, removing the need for the majority of comments, and most companies will have the associated ticket numbers or design discussions attached to the MR/PR.

I think there will still be rare situations where comments are absolutely needed, but in these rare cases they should probably refer to an external resource (a bug report for a specific library, an incident that required a specific fix, etc.)

I typically do look at the commit history of a part of code if I'm not familiar with it and I'm going to make changes there

> So they don’t have time to write the code clearly, but they somehow magically have time to read and review all the comments and to keep them in sync with the code? And the reviewers too?

Exactly. I used to love writing comments, but they have become for me a last resort. I'd rather put the information I'm trying to convey almost anywhere else. Variable names, method names, improved interfaces, better object relationships, doc strings, test code, test names, commit comments, or my colleagues' heads.

Having information in your colleagues heads only is exactly how you create organisational friction to begin with (now newcomers are likely required to ask questions to your team directly). Also over time this information gets completely lost (forgotten by people or when they leave the company).

Oh no, asking questions! The horror! If people start communicating, next thing you know they'll be collaborating, and then they might even eventually form a supportive, cohesive team. And we can't have that.

Multiple languages and documentation tools disagree on "comments don't compile/test" fwiw. You definitely can do this, in any language (though some make it much easier than others).

Though I fully admit that automated tests cover nothing related to explanations / things that aren't inherently true or false.

Personally I've wanted a way to link code to comments, not just the reverse, so I can change code here and be notified that it affects comments over there, especially during review time (just show every related comment next to the change). It seems literally essential for reliable documentation, but I haven't yet seen it except maybe in WEB (the literate programming language) or similar.

> I fully admit that automated tests cover nothing related to explanations

but ... it's the explanations that are important.

I mean there are plenty of tools to check that a comment matches a function signature or otherwise describes the properties of a bit of code. But who needs that? At least in a strongly typed language, reproducing the signature or doing anything else that reflects existing code within a comment adds very little.

Anyway, I am not arguing against comments. I'm just arguing that they can't somehow magically reduce technical debt. Or that they have anything at all to do with technical debt. Or that the OP made any sense at all.

>but ... it's the explanations that are important.

Often, yes! But you can also sometimes mechanically detect when what you're claiming might no longer be true, even if you can't assert the full content. E.g. "X does Y when you Z, so you should QWERTY periodically" -> check X,Y,Z in a slightly relevant way. Maybe have an example QWERTY call that does nothing but compile.

If a check like that fails, it means something has changed, which is an ideal time to check that documentation again. If it's not relevant, just fix the test. If it is, it shows why these systems are valuable.

(Yes, it's a change-detector test, which everyone hates for good reasons. They work great for things that are important but can't be sufficiently tested though, because the alternative is no automation at all)

Plus, the content that's truly hardest to check this way (high level conceptual docs, etc) is also generally the least likely to change in a meaningful way.

This sounds very complicated to me. It seems like a form of meta programming. It doesn’t excite me. If you can work it out from the code, why do you even need the comment?

Maybe it’s because I’m old and stupid, but I think that simplicity, efficiency and correctness are virtues, and I find it difficult to see how this qualifies.

Because people's first interaction with your code is frequently your documentation, not your code. And that sets a lot of expectations, and if it disagrees with reality it impacts how they view your project as a whole.

With enough interactions, and in the right areas, extra effort can pay for itself pretty quickly.

> Personally I've wanted a way to link code to comments, not just the reverse, so I can change code here and be notified that it affects comments over there,

If your code is separated from comments explaining it so much thag this isn't visibly obvious on review, there’s probabky a bigger problem than “I don’t have a way to link commebts to distant code and vice versa.”

Almost all larger documentation tends to be very separated from the code it's describing, e.g. conceptual docs that cover the whole thing.

And fairly often that's significantly more useful information, or in a much more useful format, than the documentation of X on its own.

That makes sense and traceability is useful there. Not what I would describe as “comments”, which shaped my original response, but that’s semantics, not substance.

> Comment bit rot is inevitable, because comments don’t compile and can’t be tested

Not true in Rust

How do you compile and test "// This method cannot be altered in any way because X tool will break" ?

If I've written a comment, and I have, it's because I have to move on, not because I think it's adding an extra layer of quality.

I don't want to write a comment, I'd rather write clean code that looks good, but when I run out of time to spend on a problem, and I don't think the code is clear enough, I think then it's acceptable to add a comment.

I just think too many devs have their egos wrapped up into their jobs, so hearing, "Commenting is failure!" evokes an emotional response. What these devs don't realize is you can make no mistakes and still "fail" to write clean code, and that's totally okay.

Uncle Bob is just saying that pulling out a comment before you've tried is premature. Try to avoid it first, if you have time to.

Exactly. A comment is the last step. I strive to write no comments, but if I feel that's the best option I will. In my opinion it is very rarely the best option.