SQL Clone
SQLServerCentral is supported by Redgate
 
Log in  ::  Register  ::  Not logged in
 
 
 

Better Comments

By Steve Jones,

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.

 
Total article views: 59 | Views in the last 30 days: 59
 
Related Articles
BLOG

Are you a DBA? You might Be!

 Are you a DBA? You might Be! On Twitter, people do a lot more than gossip and post messages about ...

BLOG

Sales People & Commission

I saw this post by Neil Davidson about sales people being different that discusses how sales people ...

ARTICLE

Notes about PASS 2003 and Other Stuff

Andy wrote up some notes about the recent PASS Community Summit, plans for next year, people we met,...

FORUM

Commenting

How much detail should be used in comments, do you assume a level of understanding? One comment I ...

ARTICLE

Product Discussions, Questions, and Comments

In response to a number of suggestions, we have setup new forums where you can ask and comment about...

Tags
editorial    
 
Contribute