Formatting and Readability

  • 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.

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

  • 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

    [font="Verdana"]Samjazz[/font]

  • 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 :w00t:
    If you don't have time to do it right the first time, where will you find time to do it again?

  • 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.

  • 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.

  • I agree in part, and disagree in part.

    I agree that readable code, with tags on End If and other blocks so current or future nesting is readable, is important.

    I disagree that it's critical for formatting to be done by the initial developer; so much of that is a matter of style it's not even funny. Rather, I suggest that every developer have their preferred settings in a SQL Beautifier (like the C beautifiers of old), so when they really object to the formatting of some code, push a few buttons or copy/paste, and it's in that developer's own preferred format. Next developer, same thing.

    Doing 100% consistent, very tedious things is exactly what software excels at; let software make code 100% consistently formatted according to a set of rules.

    So, I would ask: what are the good SQL beautifiers available today that can save a set of detailed rules? ON clause on a new line or not, indented or not, indenting AND's or not, AND/OR at the beginning or the end, and so on and so forth.

  • Formatting and indenting is fundamental.

    Using a formatting tool can help a whole team sharing the same formatting standards, which is something that makes the effort even more meaningful and rewarding.

    As far as becoming replaceable, this should be seen as positive: if you're not replaceable you will keep on doing the same things over and over and never improve your career.

    -- Gianluca Sartori

  • Visual Studio formats code automagically. Our TSQL editors should too, that way we know what we really wrote. Of course I will admit to wondering what will fall out as I format TSQL written by others.

    Bill J

  • I am all in favor of appropriate indentation and comments, as well as code reviews.

    One of the other things that drives me nuts is cryptic naming of columns and variables that make no sense whatsoever. Even with comments and indentation, trying to divine the meaning of cryptic names (particularly in large scripts/stored procedures/objects/etc...) has given me many headaches over my 30ish years in the industry.

    My rule is to write the comments and the code for the next person. The same for documentation.

  • Mike B-269836 (6/18/2010)


    I am all in favor of appropriate indentation and comments, as well as code reviews.

    One of the other things that drives me nuts is cryptic naming of columns and variables that make no sense whatsoever. Even with comments and indentation, trying to divine the meaning of cryptic names (particularly in large scripts/stored procedures/objects/etc...) has given me many headaches over my 30ish years in the industry.

    My rule is to write the comments and the code for the next person. The same for documentation.

    Whenever I write comments for a block of T-SQL code, I imagine that one of the other database developers or managers, who is unfamiliar with the application or project, is standing behind me and asking me the purpose of that code block. After a year or two, if I return to a project that I developed on myself, the comments are useful even for my own understanding.

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

  • 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.

    I prefer Hungarian notation with only the 1st letter capitalized but I see that SSMS intellisense is promoting all caps for keywords. Didn't know about Ctrl+Shift+u, nice little trick.

    I just love it when I have to look into others code and lines are 200 character long; unformatted. There are little if any comments. And everything is lower cased. It looks like the code was written in the last 20 minutes of the project:-D

  • ken.trock (6/18/2010)


    I prefer Hungarian notation with only the 1st letter capitalized but I see that SSMS intellisense is promoting all caps for keywords. Didn't know about Ctrl+Shift+u, nice little trick.

    Formatting and commenting is a must! Set/make/pick some rules and be consistent. Hungarian notation on the other hand not so much. It has lost favor in many places and should also be discouraged in T-SQL as well.

    MS advises against it (not that they are the definitive ones to follow but...)

    http://msdn.microsoft.com/en-us/ms229045.aspx

    some interesting info on it:

    http://en.wikipedia.org/wiki/Hungarian_notation

    Edit:

    Unless you are actually talking about Camel Casing? That, as well as Pascal Casing I am for.

  • ken.trock (6/18/2010)


    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.

    I prefer Hungarian notation with only the 1st letter capitalized but I see that SSMS intellisense is promoting all caps for keywords. Didn't know about Ctrl+Shift+u, nice little trick.

    I just love it when I have to look into others code and lines are 200 character long; unformatted. There are little if any comments. And everything is lower cased. It looks like the code was written in the last 20 minutes of the project:-D

    I use SQL indentation, comments, and hungarian notation with underscore for variables that arn't affiliated with a specific column name (ex: @enrollment_date for enrollment_date column and @int_loop for a looping block). Practicaly all of my variable and column names have at least one underscore, because I code all in lowercase. I like coding all in lowercase, because UPPERCASE seems 80's retro, and ProperCase is in my opinion anal-retentive. All I want to think about is wether the object and variable names are descriptive, easy on the eyes, and spelled correctly so it compiles.

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

  • I use SQL indentation, comments, and hungarian notation with underscore for variables that arn't affiliated with a specific column name (ex: @enrollment_date for enrollment_date column and @int_loop for a looping block). Practicaly all of my variable and column names have at least one underscore, because I code all in lowercase. I like coding all in lowercase, because UPPERCASE seems 80's retro, and ProperCase is in my opinion anal-retentive. All I want to think about is wether the object and variable names are descriptive, easy on the eyes, and spelled correctly so it compiles.

    So I use a combination of Hungarian and PascalCasing. Maybe a bit anal-retentive but still better than no system at all.

    CERTAINLY IT WOULD SEEM THAT ALL UPPERCASE IS NOT EASY ON THE EYES.

  • select

    a.COLUMN_NAME_1,

    b.COLUMN_NAME_2

    from

    TABLE_1 a

    join

    TABLE_2 b

    on a.TABLE_1_ID = b.TABLE_1_ID

    order by

    a.COLUMN_NAME_1,

    b.COLUMN_NAME_2

    There, was that so hard?

    Good developers produce easy to read, easy to follow code. Bad developers produce unreadable, hard to follow code. It's just as simple as that.

    The only exception to that rule that I have ever seen was a blind developer, but even he at least followed a consistent style that was not that hard to follow.

    You can argue all you want about a particular style, but having a rule that is actually followed is the most important thing.

Viewing 15 posts - 16 through 30 (of 56 total)

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