Home > SQL Challenge > SQL #47 – Too many in-line comments totally destroy code readability

SQL #47 – Too many in-line comments totally destroy code readability

I have been wanting to blog about this for awhile. SQL code readability is not a topic SQL developers like to talk about. In my 10+ years of working career, I only had this topic with two co-workers. Both of them told me that I write very “readable” SQL code. One of them said he would not use the coding style to judge a SQL developer. Another co-worker told me that  he actually installed a SQL code beautifying software to make other developers’ SQL code readable, before he even attempted to modify the code.   

Commenting is always welcome in SQL code. Single line comments, multi-line comments, in-line comments are always good to see when you work on other developers’ SQL code, until you realize that not only the comments itself have no readability, but also the messy comments totally destroy the readability of the code.

I find myself recently not only spending time to beautify the SQL code, but also to beautify the comments, especially the in-line comments.

Multi-line comments in the header portion of the procedure

It’s my preference to have multi-line comments in the header portion of the procedure (beginning of the procedure) .

image

I also place multi-line comments in my SSIS packages by adding them as Annotation. The annotation is certainly not a sophisticated text editor. So make sure you type up your multi-line comments in a SQL/Text/Word editor, and format it with appropriate indents, then paste it to the Annotation in the SSIS package.

image

Inside the procedure body, I do not use in-line comments

Inside the procedure body, I absolutely do not use in-line comments. Instead I logically divide my code into sections and paragraphs, similar to sections and paragraphs in a book, where paragraph performs only one task, and section is the collection of small tasks.

For Sections, I’d use comments like this:

image

For paragraphs, I only use single line comments.

image

One more note before I close this post. When you design your SSIS package, and run into problems in your SQL query in an OLE DB Source in a data flow, check if you have In-line comments embedded in the query. Removing them might help to solve your problem.

Let’s work together to make our SQL code readable and beautiful with a consistent style!

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 )

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

%d bloggers like this: