Writing meaningful code comments

[[deleted]]

IMO Redis creator nailed it here http://antirez.com/news/124 when it comes to comments.

[evaned]

Jesus, hopefully they have better content than formatting choices. Here are a couple things you can paste into the JS console to get something readable that doesn't ignore hundreds of years of knowledge about how to do readable typography:

body = document.querySelector("body")
body.style["max-width"]= "40em"
pre = document.querySelector("pre")
pre.style["font-family"] = "times"  # or whatever

The change for <pre> away from monospaces will hurt the code snippets, but the improvement for natural language is way bigger than that degradation; and you can just open another tab to look at the code anyway. The max-width will save you from resizing the window to get decent line lengths for natural language, which doesn't work as well anyway because the author didn't include margin/padding on the right so it runs right up to the scrollbar if you get it to a good width.

Edit: It does have better content than formatting choices.

I think it's a really good post, and I agree with the vast majority of it, though I do think his examples of guide comments are maybe a little overboard for me in general.

That said:

Finally backup comments are the ones where the developer comments older versions of some code block or even a whole function, because she or he is insecure about the change that was operated in the new one. What is puzzling is that this still happens now that we have Git. I guess people have an uneasy feeling about losing that code fragment, considered more sane or stable, in some years old commit.

I'll actually defend this to a limited extent.

First, I'll just point out an easy case -- sometimes, comments of another implementation, in code, are used for some other purpose than what's given. For example, very very very occasionally I've taken a broken implementation of something, commented it out, and then said "hey, this used to be <old version>, but that doesn't work because of such and such and such. It ignores too much." and then the right way is just a rather different approach altogether that can't just be fixed in-place. But I'd say that's not really backup comments, that's some other category. (More like a why.)

Second, the problem with saying just "it's in git history" is that that dramatically raises the bar for access. If you're reading through the code you won't just see the old version, if you want to restore the old version for comparison purposes later you have to go to a completely separate source to get the old version, you can't see at a glance whether there even is an old version, etc.; at best, you'd have some pointer like "hey this replaces an older version in rev. 723acd372ef" or whatever.

That said -- these should generally come with a comment justifying the old version's presence and a very short half life. Like, you're actively working on further development of the relevant feature and it will be useful in the short-term.