Click here to Skip to main content
13,632,101 members
Click here to Skip to main content
Add your own
alternative version

Tagged as


4 bookmarked
Posted 26 Jun 2010
Licenced CPOL

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

, 26 Jun 2010
Rate this:
Please Sign up or sign in to vote.
Learn the benefits of using this simple technique to design and document your code


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.


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 CanUserDrink(ByVal Age As Integer, _
	ByVal HasLicense As Boolean) As Boolean 
    'If the user is of the legal drinking age  
    'If the user has a drivers license 
    'Return success to the caller 
    'Otherwise the user does not have a drivers license 
    'Return Failure to the caller 
    'Otherwise the user is too young 
    'Return Failure to the caller 
End Function 

Public Function CanUserDrink(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 
            'Return Failure to the caller 
            Return False  
        End If  
    'Otherwise the user is too young 
        '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.


  • 27th June, 2010: Initial post


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Software Developer
United States United States
I'm a 28 year old software engineer from Tennessee. I've been programming since I was 13 years old. I'm fortunate enough to be able to do what I love for a living.

VB.NET, ASP.NET, C#, assembly, HTML, JavaScript, AJAX

I'm MCP, MCAD, MCSD.NET certified.

follow me on twitter

You may also be interested in...


Comments and Discussions

GeneralMy vote of 2 Pin
swampmonster14-Feb-11 10:46
memberswampmonster14-Feb-11 10:46 
GeneralMy vote of 5 Pin
slnsimha19-Jul-10 3:22
memberslnsimha19-Jul-10 3:22 
GeneralRe: My vote of 5 Pin
buddy.james1-Jan-11 22:26
memberbuddy.james1-Jan-11 22:26 
GeneralGood Idea Pin
Maher Elsayed12-Jul-10 10:47
memberMaher Elsayed12-Jul-10 10:47 
GeneralRe: Good Idea Pin
buddy.james1-Jan-11 22:29
memberbuddy.james1-Jan-11 22:29 
GeneralMy vote of 3 Pin
Abhinav S9-Jul-10 7:33
memberAbhinav S9-Jul-10 7:33 
GeneralMy vote of 4 Pin
TomS456-Jul-10 15:53
memberTomS456-Jul-10 15:53 
GeneralDesign and Document .... Pin
TomS456-Jul-10 15:52
memberTomS456-Jul-10 15:52 
GeneralRe: Design and Document .... Pin
bjames026-Jul-10 16:11
memberbjames026-Jul-10 16:11 
TomS45 wrote:
Sorry, mate. But this concept has been around for all the 40 years I've been pounding out code. It's called "pseudocode" - english, or whatever your native tongue is, statements that define the flow of the program. I've worked on teams that produced 1000's of lines of pseudocode that, when coded and cleanly compiled, had very few bugs. We used the pseudocode to do another "old" concept, the structured walkthrough, which often identified errors for correction before the first line of code was actually written.
I taught programming principles for over 15 years and always introduced these concepts to my students. But it is nice to see these tried and true techniques taught even if the names have changed.
Thanks for taking the time to write this article. Just remember, the statement I = I + 1 DOESN'T need a comment.

Thanks for the feedback.

I picked up the idea from the great book "Code Complete" (which should be on every developers bookshelf).

I was suprised at all of the negative comments regarding this strategy.

Thanks again for the positive feedback..

I will update the article to mention pseudocode.

Thanks again.
GeneralMy vote of 5 Pin
boundbystars5-Jul-10 17:53
memberboundbystars5-Jul-10 17:53 
GeneralMy vote of 2 Pin
sam.hill27-Jun-10 8:50
membersam.hill27-Jun-10 8:50 
GeneralRe: My vote of 2 Pin
bjames0228-Jun-10 22:03
memberbjames0228-Jun-10 22:03 
GeneralWrite understandable code Pin
Danielku1527-Jun-10 7:49
memberDanielku1527-Jun-10 7:49 
GeneralRe: Write understandable code Pin
bjames0228-Jun-10 22:03
memberbjames0228-Jun-10 22:03 
QuestionToo many comments? Pin
PIEBALDconsult27-Jun-10 3:59
mvpPIEBALDconsult27-Jun-10 3:59 
AnswerRe: Too many comments? Pin
bjames0228-Jun-10 3:58
memberbjames0228-Jun-10 3:58 
AnswerRe: Too many comments? Pin
bjames0212-Jul-10 17:20
memberbjames0212-Jul-10 17:20 
GeneralFormatting Pin
Brady Kelly27-Jun-10 1:01
memberBrady Kelly27-Jun-10 1:01 
GeneralRe: Formatting Pin
bjames0228-Jun-10 3:56
memberbjames0228-Jun-10 3:56 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web04 | 2.8.180712.1 | Last Updated 27 Jun 2010
Article Copyright 2010 by bjames02
Everything else Copyright © CodeProject, 1999-2018
Layout: fixed | fluid