SQL Clone
SQLServerCentral is supported by Redgate
 
Log in  ::  Register  ::  Not logged in
 
 
 


Formatting and Readability


Formatting and Readability

Author
Message
blandry
blandry
Ten Centuries
Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)Ten Centuries (1.4K reputation)

Group: General Forum Members
Points: 1415 Visits: 723
As much as the content of this editorial is good, I am amazed, stunned and disappointed that there is not even ONE single mention of the most basic element of programming - commenting your code!!!

In my 30 years of development and managing programmers I have driven plenty of them crazy when I have rejected code that is not commented. PROGRAM CODE IS A COMPANY ASSET - and thus commenting your code is as important as being able to understand a corporate financial statement because it is explained.

Commenting code not only benefits any new developer being able to pickup and manage code, it also helps the very developer who creates the code. When you have been at this as long as I have, you are going to run into times when you are asked to go back to old code (sometimes even a decade old) and make changes - when you comment your code you capture thoughts of what you were doing and what your approach was.

To pen an editorial about "readability" is nice - but it is NOT readability that truly matters - code comments do, and as I have said and will stress again - its a company asset, developers don't "own" code, the company does. Just as you might have some new appliance added to your house and then have it explained by the installer, code comments are simply essential and the FIRST element to any "readability".

Its a shame that he author left this out of the editorial - thats like talking about a sandwich and never mentioning bread.

There's no such thing as dumb questions, only poorly thought-out answers...
graymer
graymer
SSC Veteran
SSC Veteran (287 reputation)SSC Veteran (287 reputation)SSC Veteran (287 reputation)SSC Veteran (287 reputation)SSC Veteran (287 reputation)SSC Veteran (287 reputation)SSC Veteran (287 reputation)SSC Veteran (287 reputation)

Group: General Forum Members
Points: 287 Visits: 287
READABILITY is a must. I can't stand coming in behind someone else and trying to figure out where the end of a statement is or if they've got useless SQL crammed into their horrible coding.

Commenting is a must too, it's so easy to put in a '--end of blahblah IF statement' to make things so much easier to find. Sometimes you feel like commenting of something like that is silly, but when you're hunting through hundreds of lines of SQL later and you're wondering where you're at it's nice to know that you terminated your IF statement.

I have a few things I like to do make things more readable too, like using tab to line up all my data types in a declare block. I know it takes up space doing it each variable on it's own line but it makes it a lot easier for me to read.

I do the same with my inital sets too where I tab out after my variables and line the equals up.

Another quirk I do is put my commas at the beginning of each line in a declare so if I have to comment out a variable that I'm no longer using. It's all on one line and I don't have to worry about forgetting it and errors popping up to remind me.

Also, I think it's important to capitalize keywords too. Something handy for that is using highlight the keyword you want to upper case and use Ctrl+Shift+u. Back to one of the the reasons I tab out my data types in my declare if I'm going back through my SQL and I'm cleaning it up I can use a Alt+'mouse select' and Ctrl+Shift+u and it'll upper case the highlight block easily.
roger.plowman
roger.plowman
Hall of Fame
Hall of Fame (3.2K reputation)Hall of Fame (3.2K reputation)Hall of Fame (3.2K reputation)Hall of Fame (3.2K reputation)Hall of Fame (3.2K reputation)Hall of Fame (3.2K reputation)Hall of Fame (3.2K reputation)Hall of Fame (3.2K reputation)

Group: General Forum Members
Points: 3198 Visits: 1433
Amen to readability, and a double-plus-amen to comments.

You need *both*.

I've been in the unfortunate position of having a boss who considered comments nothing but time-wasting fluff. He reprimanded me for puttting *too many* comments. Smile

Three months later commenting was a best practice at that company. I like to think I had some small part in that...

Seriously, nicely formatted code makes the intent clearer. Correctly indenting code makes the intent of the code clearer. Comments explain the intent.

What part of clear code and explanation of intent is bad?

I also have had to come in after other programmers and take on huge projects that liked to use X, Y, I, Amount, etc as variable names. Yuck.

I'll say it again. Clarity of code = clarity of purpose. Comments = explanation of intent. This is not something anyone should be debating. The *hows*, yes. Not the *if*.
antiflu
antiflu
SSC Rookie
SSC Rookie (26 reputation)SSC Rookie (26 reputation)SSC Rookie (26 reputation)SSC Rookie (26 reputation)SSC Rookie (26 reputation)SSC Rookie (26 reputation)SSC Rookie (26 reputation)SSC Rookie (26 reputation)

Group: General Forum Members
Points: 26 Visits: 53
By the way, something that helped me is starting to use Common Table Expressions (CTE). It really helps to organize heavily nested code and make it readable.

(For those who don't know what I mean:

WITH a AS ( complex query ),
b AS ( complex query ),

SELECT a.*, a2.key
LEFT JOIN a ON criteria AS a2
LEFT JOIN (SELECT * FROM a INNER JOIN b)
etc...

You can use the expressions multiple times in the query afterwards but even when you don't, it already becomes more readable.

Has anyone got experience with the automatic query formatters? I already found out that the one by Red Gate (SQL Prompt) is working well, the cheaper one SQL Pretty Printer already caused some crashes...
Jeff Moden
Jeff Moden
SSC Guru
SSC Guru (339K reputation)SSC Guru (339K reputation)SSC Guru (339K reputation)SSC Guru (339K reputation)SSC Guru (339K reputation)SSC Guru (339K reputation)SSC Guru (339K reputation)SSC Guru (339K reputation)

Group: General Forum Members
Points: 339181 Visits: 42614
Agreed... both formatting and appropriate commenting are essential ingredients to good code.

--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.
If you think its expensive to hire a professional to do the job, wait until you hire an amateur. -- Red Adair

Helpful Links:
How to post code problems
How to post performance problems
Forum FAQs
Eric M Russell
Eric M Russell
SSC-Forever
SSC-Forever (43K reputation)SSC-Forever (43K reputation)SSC-Forever (43K reputation)SSC-Forever (43K reputation)SSC-Forever (43K reputation)SSC-Forever (43K reputation)SSC-Forever (43K reputation)SSC-Forever (43K reputation)

Group: General Forum Members
Points: 43261 Visits: 12021
Talking about the importance of code formatting and naming conventions in the context of computer programming is like talking about fairness in the context of politics. Everyone nods and agrees when you talk about it in an abstract way, but start talking specifics and providing actual examples, and people start disagreeing real quick.


"The universe is complicated and for the most part beyond your control, but your life is only as complicated as you choose it to be."
SamJazz
SamJazz
SSC-Enthusiastic
SSC-Enthusiastic (117 reputation)SSC-Enthusiastic (117 reputation)SSC-Enthusiastic (117 reputation)SSC-Enthusiastic (117 reputation)SSC-Enthusiastic (117 reputation)SSC-Enthusiastic (117 reputation)SSC-Enthusiastic (117 reputation)SSC-Enthusiastic (117 reputation)

Group: General Forum Members
Points: 117 Visits: 91
I strongly agree with the benefits of formatting as described in the editorial, but why leave this at an individual level?

Formatting and commenting standards should be set at a company level because consistancy is a very important part of this equation. Ideally, any developer can read any other developer's code and not be able to distinguish who wrote what based on formatting. I have been a developer since 1981 and have found that this principle will never fail your company. Also fire the SOB who writes sloppy code intentionally for job security. True job security (if there can be such a thing in this age) is found by being among the best at what we do: writing fast, efficient, defect free, and maintainable code at a rapid pace.

Sam Frabotta

Samjazz
katedgrt
katedgrt
SSC-Addicted
SSC-Addicted (445 reputation)SSC-Addicted (445 reputation)SSC-Addicted (445 reputation)SSC-Addicted (445 reputation)SSC-Addicted (445 reputation)SSC-Addicted (445 reputation)SSC-Addicted (445 reputation)SSC-Addicted (445 reputation)

Group: General Forum Members
Points: 445 Visits: 990
gabriel.raymer (6/18/2010)
READABILITY is a must. ... I can use a Alt+'mouse select' ...


I do everything you said gabriel, plus reducing my tabs to 3 spaces so I can use indentation without eating up the whole page (good to have a team standard on that as well), but OMG I did not know this!!! Thank You!!

Cool Kate The Great w00t
If you don't have time to do it right the first time, where will you find time to do it again?
Steve Jones
Steve Jones
SSC Guru
SSC Guru (223K reputation)SSC Guru (223K reputation)SSC Guru (223K reputation)SSC Guru (223K reputation)SSC Guru (223K reputation)SSC Guru (223K reputation)SSC Guru (223K reputation)SSC Guru (223K reputation)

Group: Administrators
Points: 223796 Visits: 19628
I think this is one place where the lack of code reviews happening is hurting code. When multiple people have to work with code, standards and comments get enforced fairly quickly to ensure readability.

Reviewing code people submit here in articles, I've seen some truly horrendous formats submitted that make it hard to follow the code.

Follow me on Twitter: @way0utwest
Forum Etiquette: How to post data/code on a forum to get the best help
My Blog: www.voiceofthedba.com
Bradley Deem
Bradley Deem
Ten Centuries
Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)

Group: General Forum Members
Points: 1277 Visits: 1248
We use SQL Assistant http://www.softtreetech.com for multiple functions among them code formatting. SQL Assistant uses formatting templates that can be tailored for each user. This allows us to have our individual styles giving us the ability to format a colleage's code with just two key strokes (by default) ctrl + F11 to our liking.

The only problem with inconsistent formatting styles comes from code diffs during version control, but for the most part it's not an issue.
Go


Permissions

You can't post new topics.
You can't post topic replies.
You can't post new polls.
You can't post replies to polls.
You can't edit your own topics.
You can't delete your own topics.
You can't edit other topics.
You can't delete other topics.
You can't edit your own posts.
You can't edit other posts.
You can't delete your own posts.
You can't delete other posts.
You can't post events.
You can't edit your own events.
You can't edit other events.
You can't delete your own events.
You can't delete other events.
You can't send private messages.
You can't send emails.
You can read topics.
You can't vote in polls.
You can't upload attachments.
You can download attachments.
You can't post HTML code.
You can't edit HTML code.
You can't post IFCode.
You can't post JavaScript.
You can post emoticons.
You can't post or upload images.

Select a forum

































































































































































SQLServerCentral


Search