#975 – Guidelines for Commenting Your Code

The primary goal of including comments in your code is to make the code + comments self-documenting enough that a developer other than the original author can understand what the code does and how it does it.

Guidelines for well commented code include:

  • Wherever possible, the code should “self document”:
    • Meaningful names for variables and methods
    • Consistent layout
    • Modularized code — each method performs a single task
    • Minimize nesting, where possible
  • Write effective comments:
    • Don’t just repeat what the code does
    • Use a comment to summarize a block of code that follows the comment, providing a high-level description of what the code does
    • Describe what and why, rather than how.  The code describes how and sometimes what.  Comments add to the what and also talk about why.
    • Modify comments when you modify code, if appropriate (i.e. keep the comments current)
    • Don’t comment tricky code–rewrite the code
    • Write for humans
Advertisements

About Sean
Software developer in the Twin Cities area, passionate about .NET technologies. Equally passionate about my own personal projects related to family history and preservation of family stories and photos.

One Response to #975 – Guidelines for Commenting Your Code

  1. Pingback: Sony PlayStation 4 In The Daily Six Pack: November 19, 2013

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

%d bloggers like this: