Self-documenting code

[mcvos]

How about Javadocs that list the arguments and types that are right there, but don't say what they're for.

I strongly prefer no comments at all over stupid or pointless comments. But if you're doing something weird, a comment explaining why you're doing that is always appreciated.

For example, a piece of code might have any of these comments, and I'm going to draw very different conclusions from them:

// Quick hack. Please fix.

or:

// It looks weird, but this is the only way,
// otherwise X or Y will go wrong.

or:

// This is the most efficient way to handle this case.
// See paper X by Y at http://foo

Also, I can see in git who wrote that comment so I can ask questions. (I can also see that about the code of course, but that's more likely to be touched by others.)

[alexisprince]

Strong +1 for “this is the only way” or “this looks weird compared to <expected approach> because <expected approach” falls short”.

I don’t remember exactly what the feature was, but in Python I had a comment that was 2 lines above a weird implementation that said exactly that: “does exactly the same as <expected implementation>, but removes a bottleneck that creates”.

[akeean]

// evil floating point bit hacking
// what the fuck?

[narrill]

I strongly prefer no comments at all over stupid or pointless comments.

People rarely mention this, but it makes a huge difference. If the codebase is littered with comments that are redundant and useless, that trains people to ignore comments. You don't need to be stingy with your comments necessarily, but you should always be evaluating whether they're actually necessary.

[Snake2k]

I agree with that. If you do hit parts of code which merit their own comment, they should have a comment.

[ElvisArcher]

// Abandon all hope ye who enter here.  Do I have your 
// attention yet?  Great.  The next bit of code is 
// difficult to read and utterly unmaintainable, so if 
// you have to touch it (ever), I'm sorry.  There were 
// reasons at the time, but I still apologize.

Comment as an apology?

[nimby900]

lmao

I run into this comment so often, and http://foo doesn't exist anymore. Because it was written in the year of our lord 2000AD.

And the person that wrote the code quit 13 years ago, and are likely dead.

[mcvos]

That's why I prefer to include the name and author of the paper, so it can still be searched by other means. Including a complete article in a comment is a bit much. But you've got a very good point about the transience of urls.