Documenting Your Code

Project Management

If you are anything like me, you probably do a horrible job of commenting your T-SQL code. We could all use a few tips on how to better comment your code, both in T-SQL and in other environments. Part of what makes a great developer is his or her ability to write great code, but it isn’t always obvious what the code does without some analysis. The unfortunate truth is that not every person who has made code changes in your production environment is a great programmer. In a corporate environment there are usually a lot of people who have touched the code over the years, so it isn’t always obvious who originally wrote the code, the intended purpose of the code, what has changed in the business logic over the years, and what changes are incorporated into the current code base. With some of the production code in use today, your business applications suffer from code written many years ago (sometimes a decade ago) and that long development cycle might include more than a few code changes from more than a couple of developers.


So now you are asked to make a code change to existing procedures and the indecipherable variable names, questionable techniques, or confusing logic might make it almost impossible to do anything quickly or with confidence. Usually the the person who wrote that original code has been gone for years and you must rely on the code comments for any clue as to the purpose and logic of the code segment.

You should be a believer in code comments. The more comments you insert into your code means not only will it be easier for you to remember the code between changes, but your co-workers (or eventual replacement) will have an easier job in the future. As a minimum, methods should begin with a brief header that includes a description of the purpose, who wrote the code, the date the code was written,  input and output parameters, and a list of any changes. Long code blocks and loops should have a description what describes what the original developer intended.

As mentioned before, commenting your code is nothing more than a repeatable process that needs to be followed as you write the code.  Some of the important information that should be included in your comments:

  • Header
    • Object Name
    • Business Process
    • Purpose
    • Detailed Description
    • Databases
    • Dependent Objects
    • Called By
    • External Document Reference
    • Revision History
      • Revision Number
      • Change Management Request or Ticket Number
      • Date
      • Developer
      • Change Summary
  • Inline comments
    • Description of the code block
    • Summary of procedure or explanation of code logic
    • As the code is updated reference the applicable revision number to correlate the comments
  • External comments
    • You can associate a readme.txt file with the Visual Studio project, stored procedure, or ETL package to provide detailed information, attachments to explain business logic, etc. 

Commenting Best Practices

  • Try to comment the overall code and explain what the code is doing in simple terms. Try to include enough comments so that any mid-level DBA or developer looking at the code can understand what the code is trying to accomplish
  • Try to develop a standard code block so that relevant information is easily inserted and the information format can be easily understood by future developers
  • Try to insert a comment in all major code sections, including critical minor sections where the logic can be easily misunderstood
  • As you begin to enhance code that was developed before you put your commenting process in place, update the code with the summary and inline comments so the code is standardized, but also to ensure you understand what the code is doing.

Examples and recommendations for documenting your code can be found here, here, and here.


Leave a Reply

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

You are commenting using your 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