#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

About Sean
Software developer in the Twin Cities area, passionate about software development and sailing.

2 Responses to #975 – Guidelines for Commenting Your Code

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

  2. Mason says:

    Comments should indicate WHY code does what it does.

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 )

Facebook photo

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

Connecting to %s

%d bloggers like this: