Formatting and Readability

Question

Formatting and Readability

Viewing 11 posts - 46 through 55 (of 55 total)

You must be logged in to reply to this topic. Login to reply

Eric M Russell SSC Guru Points: 125523 More actions · Answer 1

niall.baird (6/23/2010)
Commenting:
I like to see a comment block/change register at the top of each stored proc/function, something like
/* ************************************
Name: pu_mytable
Purpose: Updates dbo.MyTable with values from dbo.MyOtherTable
Date Version Author Description
***********************************
1/1/2010 1.0 Great Coder Created
2/1/2010 1.1 Great Coder Removed cursor, changed to set based update
************************************ */
but within the code, I like to see explanations before something funky - I don't believe its necessary to comment where something is blatently obvious.
I also like to have my internal comments using 'single line' commenting (--) rather than block commenting (/* */)
Also, any time you make a change, mark it with the version number!!!!!

The structure of your commenting header is very similar to the type I use, but I always enter comment dates in YYYY/MM/DD format, so I can more easily search text in scripted objects using a regular expression tool.

"Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho

david_wendelken SSCrazy Points: 2388 More actions · Answer 2

[font="Courier New"]

This is in the format used in an earlier post:

select

a.COLUMN_NAME_1,

b.COLUMN_NAME_2,

b.COL_NAME_3,

b.COLUMN_4,

b.COLUMN_NM_5,

b.COLUMN_NAME_6

from

TABLE_1 a

join

TABLE_2 b

on a.TABLE_1_ID = b.TABLE_1_ID and

a.TABLE_1_ID2 = b.TABLE_1_ID2

order by

a.COLUMN_NAME_1,

b.COLUMN_4,

b.COLUMN_NM_5,

b.COLUMN_NAME_6

I prefer this format:

select

a.COLUMN_NAME_1

,b.COLUMN_NAME_2

,b.COL_NAME_3

,b.COLUMN_4

,b.COLUMN_NM_5

,b.COLUMN_NAME_6

from

TABLE_1 a

joinTABLE_2 b

on a.TABLE_1_ID = b.TABLE_1_ID

and a.TABLE_1_ID2 = b.TABLE_1_ID2

order by

a.COLUMN_NAME_1

,b.COLUMN_4

,b.COLUMN_NM_5

,b.COLUMN_NAME_6

[/font]

From an editing point of view, the commas line up vertically in each section. I don't have to scan multiple lines to figure out which line is missing the comma. It's also easier to comment out a line starting with a comma when debugging.

Ands/Ors go to the front fo the line instead of the end of the line, for the same reasons. In addition, one is much less likely to mix ands/ors by mistake if they all line up vertically. Nested ands/ors are parenthesized and vertically aligned at their respective nesting levels.

Jeff Moden SSC Guru Points: 1003872 More actions · Answer 3

david_wendelken (6/30/2010)
It's also easier to comment out a line starting with a comma when debugging.

Actually, it's not. It's only easier to comment out the last line with leading commas. If you use trailing commas, its easier to comment out the first line. Either way, the intermediate lines require the same amount of effort to comment out.

--Jeff Moden

RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
First step towards the paradigm shift of writing Set Based code:
________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.

Change is inevitable... Change for the better is not.

Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally)

spaghettidba SSC Guru Points: 105732 More actions · Answer 4

Jeff Moden (6/30/2010)
david_wendelken (6/30/2010)
It's also easier to comment out a line starting with a comma when debugging.
Actually, it's not. It's only easier to comment out the last line with leading commas. If you use trailing commas, its easier to comment out the first line. Either way, the intermediate lines require the same amount of effort to comment out.

I think it's just a matter of personal preferences.

I prefer trailing commas, but it's just my way of seeing things. I think it's more like the way I would write a sentence in plain English (Italian?).

I like to think that my code reads like spoken language.

-- Gianluca Sartori

niall.baird Hall of Fame Points: 3468 More actions · Answer 5

I personally prefer leading commas, as they're much easier to see, especially when you line them all up, but in response to Jeff, while you're correct in that if you comment out one line, its the same amount of effort whether you use leading or trailing commas, if you're doing a little more than just commenting out one line, ie comment out one line, add another line etc, it is much easier to see where you've missed a comma if you use the leading ones.

Steve Jones - SSC Editor SSC Guru Points: 734498 More actions · Answer 6

Jeff Moden (6/30/2010)
david_wendelken (6/30/2010)
It's also easier to comment out a line starting with a comma when debugging.
Actually, it's not. It's only easier to comment out the last line with leading commas. If you use trailing commas, its easier to comment out the first line. Either way, the intermediate lines require the same amount of effort to comment out.

I agree with this. same effort.

For me, I usually know 1 or 2 fields when I'm working on something. Don't always know which ones I want to add later, or take out for testing. Since I often remove the last line, I use leading commas.

It's 6 of one, but your shop should agree on a standard.

spaghettidba SSC Guru Points: 105732 More actions · Answer 7

Standards... that's why I love formatting tools: everyone with the same formatting standards, like it or not.

BEGIN AD

We use SQLRefactor and we're very happy with it. I've seen around other tools that do a very good job at formatting and allow much more options that SQLRefactor, but more options can mean different standards, so a limited set of options is welcome.

END AD:-)

-- Gianluca Sartori

niall.baird Hall of Fame Points: 3468 More actions · Answer 8

Ah yes, but you can set sql refactor up to format however you like. Mine is set to leading commas, 'on' clauses on a separate line, 2 spaces indent etc etc.

(and if the place I work at wasn't so slow in getting approvals for purchase orders, the entire team here would be using it!!!!)

Jeff Moden SSC Guru Points: 1003872 More actions · Answer 9

niall.baird (6/30/2010)
I personally prefer leading commas, as they're much easier to see, especially when you line them all up, but in response to Jeff, while you're correct in that if you comment out one line, its the same amount of effort whether you use leading or trailing commas, if you're doing a little more than just commenting out one line, ie comment out one line, add another line etc, it is much easier to see where you've missed a comma if you use the leading ones.

Understood but, again, personal opinion. Admittedly, I'm also a bit of an odd duck. I'll put all mathematical operators at the beginning of a line and punctuation at the end of the line. Hmmm... maybe not so odd, though. 😀

--Jeff Moden

RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
First step towards the paradigm shift of writing Set Based code:
________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.

Change is inevitable... Change for the better is not.

Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally)

Nadrek SSC-Insane Points: 20039 More actions · Answer 10

niall.baird (6/30/2010)
Ah yes, but you can set sql refactor up to format however you like. Mine is set to leading commas, 'on' clauses on a separate line, 2 spaces indent etc etc.
(and if the place I work at wasn't so slow in getting approvals for purchase orders, the entire team here would be using it!!!!)

And once the entire team has it, there's no longer as much reason for everyone to follow the same standards anymore; if you don't like the code, load it up and let your software re-format it to your personal standard. Everyone else can do the same thing when it's their time to view that piece of code.

david_wendelken SSCrazy Points: 2388 More actions · Answer 11

Nadrek (7/1/2010)
And once the entire team has it, there's no longer as much reason for everyone to follow the same standards anymore; if you don't like the code, load it up and let your software re-format it to your personal standard. Everyone else can do the same thing when it's their time to view that piece of code.

I've used a number of the auto-format tools over the years. Some are quite good.

I've found that they lay out the code nicely about 98% of the time.

Sometimes it's important to break the standard layout rules to improve clarity. 😀

I haven't found an auto-formatting tool that would allow me to say "don't touch the formatting on this section right here, it's exactly the way it needs to be".