Comments in the cloud or not.

SQL is great and to make it more readable comments are wonderful.  Most code need more comments, some a lot more.  I know you're saying “Hey this code was hard to write, so it should be hard to read!”  Yea, no.  I tend write comments for me, not you.  I might have to maintain this code in the future and I’d like to at least give myself some idea of why I did certain things.

But let’s talk about HOW to do your comments.  Please use the /*  */ syntax more than not.

Why?  Take a look at this fictional code bock:

-- Getting base information for XTLOP processing select col1, --col2, col3 from mycooltable mct, othercooltable oct where  mct.id=oct.id and oct.name in (‘TIM’, ‘KELLYN’,--‘JEFF’,’RICHARD’) -- and mct.abc_id = 42 and mct.working = 101;

So, what is and what isn’t’ a comment?  Yea not exactly clear. Is the whole statement commented out? Was JEFF and RICHARD commented out of the list or just JEFF?  Are both the last two where conditions commented out? 

But Ric, the code wouldn’t look like that!  Oh yes it can.  Depending on how you are getting the code it very well may be just a block of code where line integrity is lost.  I’ve had to deal with this time and again when working on a system that I have limited access to in particular.  Sometime you can make pretty good guesses as to what the code looks like.  

But what if the code had been like this:

/*Getting base information for XTLOP processing*/ select col1, /*col2,*/ col3 from mycooltable mct, othercooltable oct where  mct.id=oct.id and oct.name in (‘TIM’, ‘KELLYN’,/*‘JEFF’,’RICHARD’*/)  /*and mct.abc_id = 42*/ and mct.working = 101;

Now it’s crystal clear what is and what is not commented out.  Yes, it is a bit harder to do the comments with the /* to start and */ to end it, but it does make for much more readable code. 

The example used here is pretty simple and likely not too hard to figure out for the most part. I’ve had to deal with this sort of thing but with hundreds of lines of code.  Not trivial to “parse” something like that.   Comments are good, use them more than not.  And when you do, please use the block comment style with /* and */ rather than the line comment style with the --.  

Now I need to talk with Jeff Smith about changing how SQL Developer comments lines.   Maybe if I send him some muffins, he’ll take interest in my suggestion.