Mike’s Dump

May 19, 2005

Code Commenting Post

Filed under: Code — mikesdump @ 1:39 pm

I read this post tonight on comments in code. This article pretty much sums up my feelings on commenting code. Here are a couple of highlights:

In general, if a comment already describes what the code does, then the comment is redundant and should be removed. Otherwise, you risk creating a misleading comment, which is worse than no comment at all. As recommended in The Pragmatic Programmer (Addison-Wesley, 2000), strive to keep each piece of knowledge in one piece, as prescribed by the DRY (Don’t Repeat Yourself) principle:

Every piece of knowledge must have a single, unambiguous, and authoritative representation within a system.

Before writing a comment, try to make the code easy to understand so that you need fewer comments. Simple, safe refactorings such as renaming classes, methods, and variables, and extracting well-named methods go a long way toward removing duplication. Then, when all else fails, please leave us a good comment.

Advertisements

Leave a Comment »

No comments yet.

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Blog at WordPress.com.

%d bloggers like this: