Infragistics JQuery controls

Design and Document your Code using PDL (Programming Design Language)

Introduction

Many of us underestimate the importance of proper code documentation through comments. Comments, when used correctly, can greatly increase the maintainability of your functions and routines, especially if there is any chance that another developer will ever need to look at your code. It's hard enough for you to remember what your intentions were for a routine you wrote 5 years ago. Imagine what it's like for someone that has no clue what you meant to do in the first place.

Background

While reading "Code Complete" (every developer, regardless of skill level, age, or programming language should own this book), I discovered a method used to comment your routines that provides so much more than just code comments.

Using the Code

This method is called PDL (Programming Design Language). The basic idea behind PDL is that you write all of the comments for your method before writing any code. Once the comments are finished, you then fill in the blanks with the implementation.

Here is an example:

Public Function CanUserBuyAlchohol(ByVal Age As Integer, ByVal HasLicense As Boolean) As Boolean 
    'If the user is of the legal drinking age     
    If Age > 21 Then 
        'If the user has a drivers license         
        If HasLicense Then     
            'Return success to the caller             
            Return True         
        'Otherwise the user does not have a drivers license          
        Else        
            'Return Failure to the caller             
            Return False
        End If  
    'Otherwise the user is too young     
    Else      
        'Return Failure to the caller         
        Return False  
    End If 
End Function
 
 

A few things to note here:

  • All of the comments are formatted logically (indentation)
  • When using this method, you write the comments first in a high level format (plain English)
  • This allows you to design the routine at a high level of abstraction
  • The requirements are in English so the routine is designed such that it can be ported to any language very easily
  • All of the thinking work is done up front
  • All that's left is to fill in the code under each comment
  • The comments written in English explain exactly what you need, so implementation is a breeze
  • Since comments are written first, you can be rest assured that all of your methods will be well documented

If another developer is reading through your code, he can simply read your high level comments until he finds the code he needs.

Points of Interest

So as you can see, using PDL has several advantages:

  • Assures code is always documented
  • Allows for high level design of routine that does not rely on a specific programming language implementation (remember the comments are plain English)
  • Once the comments are complete, coding is a snap because the logic has already been documented in plain English in the comments.

I hope you find PDL as beneficial to learn as I have. Don't forget to buy Code Complete!

Until next time.

 

kick it on DotNetKicks.com  



Pingbacks and trackbacks (1)+

Comments are closed

About the author

My name is Buddy James.  I'm a Microsoft Certified Solutions Developer from the Nashville, TN area.  I'm a Software Engineer, an author, a blogger (http://www.refactorthis.net), a mentor, a thought leader, a technologist, a data scientist, and a husband.  I enjoy working with design patterns, data mining, c#, WPF, Silverlight, WinRT, XAML, ASP.NET, python, CouchDB, RavenDB, Hadoop, Android(MonoDroid), iOS (MonoTouch), and Machine Learning. I love technology and I love to develop software, collect data, analyze the data, and learn from the data.  When I'm not coding,  I'm determined to make a difference in the world by using data and machine learning techniques. (follow me at @budbjames).  

Related links

Month List