Click here to monitor SSC
SQLServerCentral is supported by Red Gate Software Ltd.
 
Log in  ::  Register  ::  Not logged in
 
 
 
        
Home       Members    Calendar    Who's On


Add to briefcase ««12345»»»

Formatting and Readability Expand / Collapse
Author
Message
Posted Friday, June 18, 2010 6:00 AM


Old Hand

Old HandOld HandOld HandOld HandOld HandOld HandOld HandOld Hand

Group: General Forum Members
Last Login: Monday, May 7, 2012 9:23 AM
Points: 304, Visits: 716
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...
Post #939512
Posted Friday, June 18, 2010 6:33 AM


SSC Journeyman

SSC JourneymanSSC JourneymanSSC JourneymanSSC JourneymanSSC JourneymanSSC JourneymanSSC JourneymanSSC Journeyman

Group: General Forum Members
Last Login: Tuesday, August 7, 2012 6:03 AM
Points: 93, Visits: 266
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.
Post #939540
Posted Friday, June 18, 2010 6:41 AM
Old Hand

Old HandOld HandOld HandOld HandOld HandOld HandOld HandOld Hand

Group: General Forum Members
Last Login: Monday, December 2, 2013 6:30 AM
Points: 346, Visits: 691
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. :)

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*.
Post #939545
Posted Friday, June 18, 2010 6:46 AM
Forum Newbie

Forum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum Newbie

Group: General Forum Members
Last Login: Tuesday, October 2, 2012 6:14 AM
Points: 4, 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...

Post #939551
Posted Friday, June 18, 2010 6:51 AM


SSC-Dedicated

SSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-Dedicated

Group: General Forum Members
Last Login: Today @ 8:27 AM
Points: 37,076, Visits: 31,637
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."

(play on words) "Just because you CAN do something in T-SQL, doesn't mean you SHOULDN'T." --22 Aug 2013

Helpful Links:
How to post code problems
How to post performance problems
Post #939556
Posted Friday, June 18, 2010 7:35 AM


SSCommitted

SSCommittedSSCommittedSSCommittedSSCommittedSSCommittedSSCommittedSSCommittedSSCommitted

Group: General Forum Members
Last Login: 2 days ago @ 6:39 PM
Points: 1,657, Visits: 4,740
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.
Post #939600
Posted Friday, June 18, 2010 7:53 AM


SSC-Enthusiastic

SSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-Enthusiastic

Group: General Forum Members
Last Login: Friday, August 22, 2014 7:08 AM
Points: 109, Visits: 83
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
Post #939612
Posted Friday, June 18, 2010 8:06 AM


SSC Veteran

SSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC Veteran

Group: General Forum Members
Last Login: Friday, December 20, 2013 12:33 PM
Points: 225, Visits: 988
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!!


Kate The Great
If you don't have time to do it right the first time, where will you find time to do it again?
Post #939620
Posted Friday, June 18, 2010 8:33 AM


SSC-Dedicated

SSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-Dedicated

Group: Administrators
Last Login: Today @ 12:38 AM
Points: 33,267, Visits: 15,436
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
Post #939645
Posted Friday, June 18, 2010 8:53 AM
Mr or Mrs. 500

Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500

Group: General Forum Members
Last Login: Today @ 5:54 AM
Points: 554, Visits: 1,197
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.
Post #939671
« Prev Topic | Next Topic »

Add to briefcase ««12345»»»

Permissions Expand / Collapse