March 25, 2015 at 8:12 am
LightVader (3/25/2015)
And the ones that would only do so because I wrote the comments first to document the process and then wrote code that implemented the process.
That's pretty much how I always create new code.
The absence of evidence is not evidence of absence.
Martin Rees
You can lead a horse to water, but a pencil must be lead.
Stan Laurel
March 25, 2015 at 8:34 am
Took me a bit to find this one but is the funniest comment I ever saw.
I know this is a kludge but it is after midnight and the deadline is tomorrow.
This was discovered about 10 years after the original software was in production. It was apparently written originally by some consultants.
_______________________________________________________________
Need help? Help us help you.
Read the article at http://www.sqlservercentral.com/articles/Best+Practices/61537/ for best practices on asking questions.
Need to split a string? Try Jeff Modens splitter http://www.sqlservercentral.com/articles/Tally+Table/72993/.
Cross Tabs and Pivots, Part 1 – Converting Rows to Columns - http://www.sqlservercentral.com/articles/T-SQL/63681/
Cross Tabs and Pivots, Part 2 - Dynamic Cross Tabs - http://www.sqlservercentral.com/articles/Crosstab/65048/
Understanding and Using APPLY (Part 1) - http://www.sqlservercentral.com/articles/APPLY/69953/
Understanding and Using APPLY (Part 2) - http://www.sqlservercentral.com/articles/APPLY/69954/
March 25, 2015 at 9:10 am
LightVader (3/25/2015)
ChrisM@Work (3/25/2015)
Jeff Moden (3/24/2015)
Eirikur Eiriksson (3/24/2015)
Wayne West (3/23/2015)
Jeff Moden (3/22/2015)
Steve Jones - SSC Editor (3/16/2015)
Eirikur Eiriksson (3/13/2015)
Digressing slightly, how would the threadizens describe the optimal code comments? Obviously the opposite of that would be the worst;-)😎
I want to ask this as well. Specifically with code examples and then the comment used (as well as place, inline, VCS, etc)
To me, it's simple and I train the Devs and DBAs that I work with on two very simple concepts.
1) If you were to remove all the code from a stored procedure or other program object, the comments that are left behind would form the basis of a functional flowchart that someone could use to rewrite the code from and, possibly, reverse engineer the requirements from.
2) I use "comment bars" to label sections of the code to make them more visually obvious. It goes hand-in-hand with #1 above.
Here's an example ...
We did a study at one of the companies I worked at. For every 10 seconds put into appropriate comments, anywhere from 20 minutes to 2 hours worth of studying the code or doing additional research was saved during any type of rework on the code. We also found that the amount of rework dropped to near zero because Developers lost track of where they were a whole lot less often and didn't have to keep everything in their head while developing.
...
Proper commenting is in our company standard and a code review can fail if the comments and formatting aren't up to snuff. It's a part of the job and everyone has learned to do it very, very well. For most of the folks, I didn't even have to break out any pork chops because of the way I trained them.
Coming soon to SQLServerCentral.com: Stairway to Proper T-SQL Comments and Documentation by Jeff Moden?[/b]
PLEEZE?!!!
+10000
Cannot think of anyone better suited for the task, Jeff when??
😎
Thanks for the vote of confidence, folks. I'll think about it. Heh... at least I know there will be two people to read it. 😀
Add one to that.
This opened my eyes up really wide: "1) If you were to remove all the code from a stored procedure or other program object, the comments that are left behind would form the basis of a functional flowchart that someone could use to rewrite the code from and, possibly, reverse engineer the requirements from."
I'm off now to inspect the ten stored procedures I've been working on for the last two weeks to see if the documentation in them would pass this test, and if it doesn't, then augment it until it does.
That one got me thinking too. I think only one or two of my projects would pass that test. And the ones that would only do so because I wrote the comments first to document the process and then wrote code that implemented the process.
To be honest, I didn't believe there was such interest in a "comments" article. I thought there'd be an overwhelming banter as to me living in a "perfect world" and it not being practical. I obviously believe quite the contrary and my "Comment Standards" has served the companies that I've enforced for have benefitted quite a bit but I didn't believe that others would be so interested.
--Jeff Moden
Change is inevitable... Change for the better is not.
March 25, 2015 at 11:07 am
Jeff Moden (3/25/2015)
To be honest, I didn't believe there was such interest in a "comments" article. I thought there'd be an overwhelming banter as to me living in a "perfect world" and it not being practical. I obviously believe quite the contrary and my "Comment Standards" has served the companies that I've enforced for have benefitted quite a bit but I didn't believe that others would be so interested.
I think there's a definite need for a good article or series showing some good methodologies for commenting. We have lots of standards: ISO defines how SQL works, Microsoft implements what they want in T-SQL, people do Hungarian notation or not, etc. It's like the once-standard answer here: "Well, there's a few different ways to do that." We can choose how we implement comments, but it's usually widely-varying from programmer to programmer with little or no standardization. And I've never seen good guidelines for documenting T-SQL code. The concept of black box comments where you could delete the code and have a good chance of reconstructing the code is just fantastic, and could make for an excellent interview technique.
And I freely admit that I don't document adequately and I've been working with SQL since 4.21a. But I'm doing better with the system that I'm developing now, it's the first grounds-up system that I've done in ages and I want to be able to safely hand it off when I leave here. Yesterday I updated my documentation to explain why I chose a Int/Identity field as the PK instead of a perfectly reasonable candidate key (and I thought long and hard about that decision, reducing truly massive table fragmentation won in the end).
There was an old joke about documentation being the castor oil of programming: programmers hate to do it, and management loves it because the programmers hate it so. But if we had good guidelines on a methodology that works, it might not taste so bad.
-----
[font="Arial"]Knowledge is of two kinds. We know a subject ourselves or we know where we can find information upon it. --Samuel Johnson[/font]
March 25, 2015 at 5:40 pm
Jeff Moden (3/25/2015)
LightVader (3/25/2015)
ChrisM@Work (3/25/2015)
Jeff Moden (3/24/2015)
Eirikur Eiriksson (3/24/2015)
Wayne West (3/23/2015)
Jeff Moden (3/22/2015)
Steve Jones - SSC Editor (3/16/2015)
Eirikur Eiriksson (3/13/2015)
Digressing slightly, how would the threadizens describe the optimal code comments? Obviously the opposite of that would be the worst;-)😎
I want to ask this as well. Specifically with code examples and then the comment used (as well as place, inline, VCS, etc)
To me, it's simple and I train the Devs and DBAs that I work with on two very simple concepts.
1) If you were to remove all the code from a stored procedure or other program object, the comments that are left behind would form the basis of a functional flowchart that someone could use to rewrite the code from and, possibly, reverse engineer the requirements from.
2) I use "comment bars" to label sections of the code to make them more visually obvious. It goes hand-in-hand with #1 above.
Here's an example ...
We did a study at one of the companies I worked at. For every 10 seconds put into appropriate comments, anywhere from 20 minutes to 2 hours worth of studying the code or doing additional research was saved during any type of rework on the code. We also found that the amount of rework dropped to near zero because Developers lost track of where they were a whole lot less often and didn't have to keep everything in their head while developing.
...
Proper commenting is in our company standard and a code review can fail if the comments and formatting aren't up to snuff. It's a part of the job and everyone has learned to do it very, very well. For most of the folks, I didn't even have to break out any pork chops because of the way I trained them.
Coming soon to SQLServerCentral.com: Stairway to Proper T-SQL Comments and Documentation by Jeff Moden?[/b]
PLEEZE?!!!
+10000
Cannot think of anyone better suited for the task, Jeff when??
😎
Thanks for the vote of confidence, folks. I'll think about it. Heh... at least I know there will be two people to read it. 😀
Add one to that.
This opened my eyes up really wide: "1) If you were to remove all the code from a stored procedure or other program object, the comments that are left behind would form the basis of a functional flowchart that someone could use to rewrite the code from and, possibly, reverse engineer the requirements from."
I'm off now to inspect the ten stored procedures I've been working on for the last two weeks to see if the documentation in them would pass this test, and if it doesn't, then augment it until it does.
That one got me thinking too. I think only one or two of my projects would pass that test. And the ones that would only do so because I wrote the comments first to document the process and then wrote code that implemented the process.
To be honest, I didn't believe there was such interest in a "comments" article. I thought there'd be an overwhelming banter as to me living in a "perfect world" and it not being practical. I obviously believe quite the contrary and my "Comment Standards" has served the companies that I've enforced for have benefitted quite a bit but I didn't believe that others would be so interested.
I beginning to think that when I wrote this article (based on a quotation from Jeff):
Make it Work, Make it Fast, Make it Pretty[/url]
Maybe I should have entitled it" Make it Work, Make it Fast, Make it Pretty... and then Comment the Crap out of it."
My thought question: Have you ever been told that your query runs too fast?
My advice:
INDEXing a poor-performing query is like putting sugar on cat food. Yeah, it probably tastes better but are you sure you want to eat it?
The path of least resistance can be a slippery slope. Take care that fixing your fixes of fixes doesn't snowball and end up costing you more than fixing the root cause would have in the first place.
Need to UNPIVOT? Why not CROSS APPLY VALUES instead?[/url]
Since random numbers are too important to be left to chance, let's generate some![/url]
Learn to understand recursive CTEs by example.[/url]
[url url=http://www.sqlservercentral.com/articles/St
March 26, 2015 at 1:09 am
dwain.c (3/25/2015)
...I beginning to think that when I wrote this article (based on a quotation from Jeff):Make it Work, Make it Fast, Make it Pretty[/url]
Maybe I should have entitled it" Make it Work, Make it Fast, Make it Pretty... and then Comment the Crap out of it."
No!!! "Make it Work, Make it Fast, Make it Pretty... whilst commenting the Crap out of it." would be much better 😉
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
March 26, 2015 at 3:06 am
Gary Varga (3/26/2015)
dwain.c (3/25/2015)
...I beginning to think that when I wrote this article (based on a quotation from Jeff):Make it Work, Make it Fast, Make it Pretty[/url]
Maybe I should have entitled it" Make it Work, Make it Fast, Make it Pretty... and then Comment the Crap out of it."
No!!! "Make it Work, Make it Fast, Make it Pretty... whilst commenting the Crap out of it." would be much better 😉
I personally love that word whilst but at a guess Jeff being American would never use it.
My thought question: Have you ever been told that your query runs too fast?
My advice:
INDEXing a poor-performing query is like putting sugar on cat food. Yeah, it probably tastes better but are you sure you want to eat it?
The path of least resistance can be a slippery slope. Take care that fixing your fixes of fixes doesn't snowball and end up costing you more than fixing the root cause would have in the first place.
Need to UNPIVOT? Why not CROSS APPLY VALUES instead?[/url]
Since random numbers are too important to be left to chance, let's generate some![/url]
Learn to understand recursive CTEs by example.[/url]
[url url=http://www.sqlservercentral.com/articles/St
March 26, 2015 at 3:12 am
dwain.c (3/26/2015)
Gary Varga (3/26/2015)
dwain.c (3/25/2015)
...I beginning to think that when I wrote this article (based on a quotation from Jeff):Make it Work, Make it Fast, Make it Pretty[/url]
Maybe I should have entitled it" Make it Work, Make it Fast, Make it Pretty... and then Comment the Crap out of it."
No!!! "Make it Work, Make it Fast, Make it Pretty... whilst commenting the Crap out of it." would be much better 😉
I personally love that word whilst but at a guess Jeff being American would never use it.
I'm British and I don't use it either 🙂
Whilst, betwixt and amongst are in the same family of words, so unless you are prepared to use all of them (ie, don't use 'whilst' and then 'among' in the same document), it is more consistent to use none.
The absence of evidence is not evidence of absence.
Martin Rees
You can lead a horse to water, but a pencil must be lead.
Stan Laurel
March 26, 2015 at 3:16 am
The worst comments use the words whilst, whence, betwixt and amongst or any of their related British-isms. 😛
Unless they're used consistently of course.
My thought question: Have you ever been told that your query runs too fast?
My advice:
INDEXing a poor-performing query is like putting sugar on cat food. Yeah, it probably tastes better but are you sure you want to eat it?
The path of least resistance can be a slippery slope. Take care that fixing your fixes of fixes doesn't snowball and end up costing you more than fixing the root cause would have in the first place.
Need to UNPIVOT? Why not CROSS APPLY VALUES instead?[/url]
Since random numbers are too important to be left to chance, let's generate some![/url]
Learn to understand recursive CTEs by example.[/url]
[url url=http://www.sqlservercentral.com/articles/St
March 26, 2015 at 3:26 am
Phil Parkin (3/26/2015)
dwain.c (3/26/2015)
Gary Varga (3/26/2015)
dwain.c (3/25/2015)
...I beginning to think that when I wrote this article (based on a quotation from Jeff):Make it Work, Make it Fast, Make it Pretty[/url]
Maybe I should have entitled it" Make it Work, Make it Fast, Make it Pretty... and then Comment the Crap out of it."
No!!! "Make it Work, Make it Fast, Make it Pretty... whilst commenting the Crap out of it." would be much better 😉
I personally love that word whilst but at a guess Jeff being American would never use it.
I'm British and I don't use it either 🙂
Whilst, betwixt and amongst are in the same family of words, so unless you are prepared to use all of them (ie, don't use 'whilst' and then 'among' in the same document), it is more consistent to use none.
I'd almost agree with this. Whilst and amongst don't appear to me to be uncommon, unless it's the HR folks I spend too much time listening to. Betwixt sounds too much like confectionary nowadays to be taken seriously. Who amongst us would dare?
For fast, accurate and documented assistance in answering your questions, please read this article.
Understanding and using APPLY, (I) and (II) Paul White
Hidden RBAR: Triangular Joins / The "Numbers" or "Tally" Table: What it is and how it replaces a loop Jeff Moden
March 26, 2015 at 4:48 am
ChrisM@Work (3/26/2015)
Phil Parkin (3/26/2015)
dwain.c (3/26/2015)
Gary Varga (3/26/2015)
dwain.c (3/25/2015)
...I beginning to think that when I wrote this article (based on a quotation from Jeff):Make it Work, Make it Fast, Make it Pretty[/url]
Maybe I should have entitled it" Make it Work, Make it Fast, Make it Pretty... and then Comment the Crap out of it."
No!!! "Make it Work, Make it Fast, Make it Pretty... whilst commenting the Crap out of it." would be much better 😉
I personally love that word whilst but at a guess Jeff being American would never use it.
I'm British and I don't use it either 🙂
Whilst, betwixt and amongst are in the same family of words, so unless you are prepared to use all of them (ie, don't use 'whilst' and then 'among' in the same document), it is more consistent to use none.
I'd almost agree with this. Whilst and amongst don't appear to me to be uncommon, unless it's the HR folks I spend too much time listening to. Betwixt sounds too much like confectionary nowadays to be taken seriously. Who amongst us would dare?
Whom amongst us??
MM
select geometry::STGeomFromWKB(0x0106000000020000000103000000010000000B0000001000000000000840000000000000003DD8CCCCCCCCCC0840000000000000003DD8CCCCCCCCCC08408014AE47E17AFC3F040000000000104000CDCCCCCCCCEC3F9C999999999913408014AE47E17AFC3F9C99999999991340000000000000003D0000000000001440000000000000003D000000000000144000000000000000400400000000001040000000000000F03F100000000000084000000000000000401000000000000840000000000000003D0103000000010000000B000000000000000000143D000000000000003D009E99999999B93F000000000000003D009E99999999B93F8014AE47E17AFC3F400000000000F03F00CDCCCCCCCCEC3FA06666666666FE3F8014AE47E17AFC3FA06666666666FE3F000000000000003D1800000000000040000000000000003D18000000000000400000000000000040400000000000F03F000000000000F03F000000000000143D0000000000000040000000000000143D000000000000003D, 0);March 26, 2015 at 6:14 am
mister.magoo (3/26/2015)
ChrisM@Work (3/26/2015)
Phil Parkin (3/26/2015)
dwain.c (3/26/2015)
Gary Varga (3/26/2015)
dwain.c (3/25/2015)
...I beginning to think that when I wrote this article (based on a quotation from Jeff):Make it Work, Make it Fast, Make it Pretty[/url]
Maybe I should have entitled it" Make it Work, Make it Fast, Make it Pretty... and then Comment the Crap out of it."
No!!! "Make it Work, Make it Fast, Make it Pretty... whilst commenting the Crap out of it." would be much better 😉
I personally love that word whilst but at a guess Jeff being American would never use it.
I'm British and I don't use it either 🙂
Whilst, betwixt and amongst are in the same family of words, so unless you are prepared to use all of them (ie, don't use 'whilst' and then 'among' in the same document), it is more consistent to use none.
I'd almost agree with this. Whilst and amongst don't appear to me to be uncommon, unless it's the HR folks I spend too much time listening to. Betwixt sounds too much like confectionary nowadays to be taken seriously. Who amongst us would dare?
Whom amongst us??
Unbeknownst to us, we have grammar police in our midst.
For fast, accurate and documented assistance in answering your questions, please read this article.
Understanding and using APPLY, (I) and (II) Paul White
Hidden RBAR: Triangular Joins / The "Numbers" or "Tally" Table: What it is and how it replaces a loop Jeff Moden
March 26, 2015 at 7:45 am
ChrisM@Work (3/26/2015)
Phil Parkin (3/26/2015)
I personally love that word whilst but at a guess Jeff being American would never use it.I'm British and I don't use it either 🙂
Whilst, betwixt and amongst are in the same family of words, so unless you are prepared to use all of them (ie, don't use 'whilst' and then 'among' in the same document), it is more consistent to use none.
I'm thoroughly American and I do occasionally use whilst and amongst, but I'm weird or possibly deranged. I can't think of having used betwixt in a while, though. Maybe I can write a SQL function to do the same as Between and name it Betwixt to bedevil those not amonst us who come after... :alien:
-----
[font="Arial"]Knowledge is of two kinds. We know a subject ourselves or we know where we can find information upon it. --Samuel Johnson[/font]
March 26, 2015 at 8:24 am
Wayne West (3/26/2015)
ChrisM@Work (3/26/2015)
Phil Parkin (3/26/2015)
I personally love that word whilst but at a guess Jeff being American would never use it.I'm British and I don't use it either 🙂
Whilst, betwixt and amongst are in the same family of words, so unless you are prepared to use all of them (ie, don't use 'whilst' and then 'among' in the same document), it is more consistent to use none.
I'm thoroughly American and I do occasionally use whilst and amongst, but I'm weird or possibly deranged. I can't think of having used betwixt in a while, though. Maybe I can write a SQL function to do the same as Between and name it Betwixt to bedevil those not amonst us who come after... :alien:
We noticed 😉
Probably explains why we like you 😀
Betwixt always seems a little Shakespearian to me.
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
March 26, 2015 at 8:25 am
dwain.c (3/26/2015)
Gary Varga (3/26/2015)
dwain.c (3/25/2015)
...I beginning to think that when I wrote this article (based on a quotation from Jeff):Make it Work, Make it Fast, Make it Pretty[/url]
Maybe I should have entitled it" Make it Work, Make it Fast, Make it Pretty... and then Comment the Crap out of it."
No!!! "Make it Work, Make it Fast, Make it Pretty... whilst commenting the Crap out of it." would be much better 😉
I personally love that word whilst but at a guess Jeff being American would never use it.
Heh... I use whatever it takes to get the point across. At work, it's sometimes considered to be an HR violation. 😛
--Jeff Moden
Change is inevitable... Change for the better is not.
Viewing 15 posts - 106 through 120 (of 156 total)
You must be logged in to reply to this topic. Login to reply