Wednesday, April 23, 2014
Home » PL/SQL » Commenting in PLSQL – Who Cares
Commenting in PLSQL – Who Cares

Commenting in PLSQL – Who Cares

PL/SQL Developer

In this article I will be discussing commenting in PLSQL, and if we really need to care about commenting our code or not. During my years as a PL/SQL developer, I have seen many types of comments, both good and bad. I will speak about some of the ways to comment that I have experienced.

Ok, let us pretend that you have gotten the task of creating a PL/SQL package that is going to be used by your whole team. How would you comment the code you are putting together? Or, would you care about commenting at all…?

“Well, my code looks pretty good, and I don’t feel I really need to comment anything”. Let me tell you something, from my own experience: If you are getting “old” (well 46 at least) like me, and you did something about six months ago, and you have done hundreds of little things between then and now….you would wish you had some comments. That is exactly why I try to comment a lot in my code, so that I can get up-to-speed as fast as possible, if I am asked to run something I did a long time ago.

Introduction

I classify comments in five different categories:

  • Object header comments
  • POCEDURE and FUNCTION header comments
  • In-line comments
  • Code change comments
  • Divider comments

Before I go on, you might already know, but just in case you do not – there are two ways to comment in PL/SQL:

The one-line comment comments everything on one line, that comes after the double hyphens.  The multi-line comment, comments everything between the start of the comment (“/*“), and the end of the comment (“*/“). I have to admit that I sometimes use the multi-line version, even if the comment is only on one line. And, sometimes you are actually forced to if i.e. your comment is in the middle area of your line.

Ok, let’s move on.

Object header comments

This is a comment that describes the object that the code is for. The object could be a stored procedure or function. It could also be a package in PL/SQL, and so on. Here is a sample of how I do my object header comments:

There are a couple of things to remark, when it comes to this kind of comments:

  1. Placement in file: If you always keep your latest code in a file, you might feel that the most logical placement for this kind of comment is in the top of your file. It would to me. Just remember, if you are working with a package, your code is stored in two parts: PACKAGE and PACKAGE BODY. When you compile your file, and look at your package code, you will find your header comments in the PACKAGE part, and not in the PACKAGE BODY PART. You will do most of your work in the PACKAGE BODY. Just something to consider.
  2. Placement inside code block: If you look at the sample above, you will see that I have put the commented lines below the start of the PACKAGE block. If you code in your file all the time, and then compile it…any comments above the start of the block will disappear when you compile your file. So, it will not be seen when you look at your code using your favorite PL/SQL editor (like TOAD, PL/SQL Developer, Oracle SQL Developer, etc).

My recommendation is to describe the content in the object (procedure, function, package, etc.)  as well as possible. At least you should have a WHEN, WHO, and WHAT section in your header comment.

I am fully aware of that things might be a little bit changed today, since we have so many ways to store our files…like in so many different types of repositories. We can i.e. use SubVersion, or maybe a company based GIT repository. Then we can comment every time we do a “commit” of changes to the repository, and even see a log of comments between versions…and even do a diff between two file versions.

Call me old-fashioned, but I actually like to see the comments in the file itself so that I can see the reasons for the different changes there.

PROCEDURE and FUNCTION header comments

Here I am not speaking about single stored procedures or functions, but rather the different functions and procedures within a package. OR, for procedures or functions you choose to put inside your stored procedure or function.

The purpose of this type of comments would be to describe the usage of this procedure, it’s parameters, etc.

Here is a sample:

The above is just an example. I usually do not use this type of comments very much. I prefer in-line commenting.

In-line commenting

This is the type of comments I definitely do most of. What I am speaking about here are comments that you can find anywhere in the code, and the main purpose is to help the reader of the code to understand some logic, the reason for calling a procedure, etc.

I classify these types of comments into:

  • Declaration comments
  • Code-helping comments

Declaration comments

These are comments where I want to group different types of declarations in my code. They are found towards the top in my PL/SQL packages. Here are some samples:

Code-helping comments

The main purpose of these types of comments is to help the reader of the code to understand what is going on. I usually try to group my code into logical groups, like shown below:

As you can see, I use a header with hyphens around for my “groups”. Then, I use a multi-line type of commenting on the different parts of the “group”. There are many ways you can organize this, but this is how I have done it for a while. I some times just use hyphens in front of the code “part”.

Code change comments

When writing this I was going back-and-forth in my head, whether I should put this under the “In-line commenting” section, or if I should dedicate a separate section for it. I feel that this was worth it’s own section.

Ok, if you put all your comments in your source-control repository, like SubVersion, GIT, CVS, etc…this might not be interesting to you, but I feel it is worth to mention.

Back in the end of the 90′s I used to work as a consultant for a company with several hundred employees. It was an international company, with offices many places around the world. They had an R&D (Research and Development) department that had set up guidelines on how to do code changes. Below is a sample on how they did the commenting (or something similar at least):

I personally find this way of commenting code a bit…too much. I had to do some code changes in some of the PL/SQL code for the accounting module for the company mentioned above, and the code just got really messy. This, since there were so many customizations compared to the core version for the project I worked on. There might be a bit more cleaner ways to do this, but in general…I almost never comment like this.

Divider comments

The last type of comments I want to mention, is what I just call divider comments. These are comments I use to i.e. divide the different procedures and functions in a package, or between the package’s variable declaration area and where the procedure and function declarations start:

I try to make these dividers searchable. That is the reason I use “##” in the comment. Then I can easily search to the next declaration part in a large package.

Conclusion

Well, as you can see, there are many different ways to do commenting in PLSQL code. And, as mentioned in this article, there are also different reasons to comment.

I hope you comment in your PL/SQL (or any other programming language) code. To me it is all about readability. Even if you don’t feel that you need any comments here and now, you might wish you had commented your advanced arbitrage (i.e.) package three years ago.

I hope you have gotten some input about commenting your PL/SQL code. If you enjoyed the article, please share it on your favorite social media channel. And, if you have any other suggestions, or comments: Use the comment section below.

In this article I will be discussing commenting in PLSQL, and if we really need to care about commenting our code or not. During my years as a PL/SQL developer, I have seen many types of comments, both good and bad. I will speak about some of the ways to comment that I have experienced. Ok, ...

Review Overview

Rate this

Summary : If you enjoyed this post, rate it to let other people know what you think. Hey...don't forget to share as well :-)

User Rating: Be the first one !
0

About TJ Abrahamsen

TJ Abrahamsen is the founder and author of OracleTuts. He has worked with Oracle since 1997. His expertise is with Oracle SQL and PL/SQL. He loves teaching others, and like to share his thoughts, ideas, and experience on his blog.