I assume most of your comment your code.

Well, you probably comment code most of the time.

I'd bet your comments have quite a bit of detail.

And you do this completely inconsistently.

That's what I'd think, or maybe just what I want. Even the best developers I know will not consistently comment code. You can drift through any project on Github and see this. Those projects on GitHub might even be better documented because people know they are public. In most corporate environments I have worked in, I'll find that when people get busy, or distracted, or even when they're experimenting to find a solution, and they don't write detailed comments. Usually only when someone fixes a bug, with a solution found quickly, do I get a really useful comment.

There are all sorts of ways that people think about commenting their code. I ran across a post from Annette Allen about adding comments. She noted that she has headers in her stored procedures and other comments. However, after a few months, she wasn't sure that the comments actually helped her. I've had that same feeling at times when looking back at comments, both mine and others.

Do you have a method for choosing the words you use to comment code? Jeff Atwood says to comment on why you did something, not what. I've seen that before, especially with version control commit comments. We often can look at code to determine what it does, and if you use a VCS extensively, then you can always see the changes that were made between versions. The comments typically give me some rationale for the work I did. Over time, I find that if I think about how I'd explain my reasoning to myself in the future, I come up with a good comment.

You might feel differently, and if so, please let me know. Perhaps there are some good ideas you have about choosing comments, and perhaps you have examples. Some might include a bug or Jira number, which I like, but others may hate. These could be comments inline in code or those you use when comimtting to a VCS.

Share some thoughts today, and if you have any entries for the best code comment, drop them here.