I write notes to my future self all the time.

Meta comment: This is bullshit and has problems with this that and the other thing. But to fix that I'd have to refactor this other module and I'm not going to do that now. And the other thing I'm drawing a blank.

Meta comment2: I don't think the code needs to do this here. But I can't prove it right now.

Meta comment3: We absolutely need to do this exactly as it is. Because otherwise bad thing happens, which you probably won't see until it hits production.

Meta comment4: This function name isn't correct. But I can't think of a name that is better.

> Meta comment: This is bullshit

I used to worry about putting emotional blurbs in comments or commit messages, but I'm starting to see their value. A commit that starts "This ugly writing is to appease Roger, the editor obsessed with AP style" lets me know three things:

- Who asked for the change - The source of the content - The fact I disagree but still do it, so future me doesn't pick fights present me avoided

Of course, it could also mean "TODO: revert this commit the minute Roger retires."

That's less about emotion and more about context, which absolutely is important to capture. Links to tracking systems, and in more dysfunctional environments, quotes from emails and water cooler conversations can help a lot when going back in time. Generally I put those in the commit message whenever it makes sense, but sometimes it's better to put it in the actual comments themselves.

On the other hand, on the rare occasion that I've commented or committed something based on emotions, I've always regretted it. Granted they never caused problems for me, just a source of internal embarrassment. Still a good enough reason to be thoughtful about what emotions you express.

> Meta comment3: We absolutely need to do this exactly as it is. Because otherwise bad thing happens, which you probably won't see until it hits production.

This is the highest purpose that a comment can fulfill - telling why you are doing something that looks stupid.

> This function name isn't correct

When dealing with articulate code I often rename the same thing multiple time while I understand it better/clarify it's purpose. Also I love how naming protects the purpose of a variable or method, mentally speaking

Couldn't agree more, except with meta comment 3 it is very important to describe the bad thing, so that future me knows if he can safely rewrite this or not.

I write multi-line commit comments whenever I do something that's not trivial or has required a large amount of reasoning to perform correctly. As in, first 80 characters explaining the high-level details with (see details) at the end. Then a number of lines with more detailed reasoning.

Most such commits are never looked at again. But every other month or so, I come across a maintenance issue where I wonder about the context of something. In many such cases, I've saved multiple days of false starts or debugging. So it pays off in the long run even if it's only me gaining something from this. (Unlikely; we're a company of 80 developers).

Yes, this.

Sometimes you have a choice of a clever way to do something, which saves a few lines and uses neat language tricks that you rarely use * , or just doing things the boring way. As long as the boring way is obvious enough, it's often the better choice.

* I'm looking at you, Ruby... :)