March 16, 2015 at 7:53 am
Steve Jones - SSC Editor (3/13/2015)
Eric M Russell (3/13/2015)
My point earlier was that this form of comment is useless; it's basically just re-stating in engligh the functional operation of a single statement. But T-SQL is declarative and verbose enough that it doesn't need such comments intended to simply describe it's function.-- Deleting from sometable where StartDate is older than 30 days.
However, this comment is better. It tells us when the change was coded, who made the change, and why we are deleting from the table in the first place.
-- 2014/02/13 J.S. TFS34621: Performance optimization. Operations requested that history older than 30 days be purged from run log table.
i tend to agree with Eric here. State the business reason, or logical reason, not what the code does.
it's all nice and true but some times the person doing the change
might not have the busies or logical reason for the change. he/she might have been told that do this here, do it fast.
hence the comment. in one of my previous companies, we had a codding rule implemented (when I started there were none)
to add a comment line to every change we do in the form ([NAME]-[DATE] OR [DATE]-[NAME] -- [Ticket/Reason] -- Explanation) minimum the date/name/ticket or reason as a way to account for time spent on the project and bill the customer.
after, we moved from sourceSafe to VNC with it's own comments
but as we were limited with the check-ins for code we still had to do the in-code comments AND the check-in comment.
now there were some Perls there. bad enough that company had to institute a proper language policy as many times they had to show the comments to the customers and it was not peaty.
March 16, 2015 at 2:53 pm
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)
Follow me on Twitter: http://www.twitter.com/way0utwest
Forum Etiquette: How to post data/code on a forum to get the best help
My Blog: www.voiceofthedba.com
March 21, 2015 at 4:24 pm
Oh this is a good topic! My favorite example of bad code was from a co-worker I used to work with. She wrote really awful code, and the comments weren't much help. She was a VB programmer so my examples of what she did is in that language.
There were two things which she did over and over again. One would be an example like this:
' March 21 Needed to add the case number
She never bothered to put in the year into the comment, she just put in the month and day. Since she was there for over 10 years, it made it difficult to know when she ever did anything.
But the coup de grace was her habit of never indenting any of her code. In fact even though Visual Studio would properly indent the code, she would go out of her way to left justify all of the code. So how do comments fit in with this? Simple, she wanted to have some way of knowing when an inner action was happening vs. an outer action, so she'd put a comment marker (in VB its the single tic character) way out at the end of the line, followed by a number. Normally her routines would go on for pages, but I'll be kind to you all and only show you an example that would fit onto a page. (This example I got by doing a Bing search for processing a loop in VB. Please note that the original code that I found was properly indented and commented. I'm making it the way that my former co-worker wrote it so that you'll see what we had to work with.)
Dim strSongNames() As String
Dim blDimensioned As Boolean
Dim strText As String
Dim lngPosition as Long
blDimensioned = False
Do '1
strText = InputBox("Enter a song name:") '2
If strText <> "" Then
If blDimensioned = True Then '3
ReDim Preserve strSongNames(0 To UBound(strSongNames) + 1) As String '4
Else '3
ReDim strSongNames(0 To 0) As String '4
blDimensioned = True
End If '3
strSongNames(UBound(strSongNames)) = strText '4
End If '2
Loop Until strText = "" '1
And often those comments were a LONG WAYs out there at the end of the line, you'd have to scroll to the right to see them. I have no idea why she thought that was better than properly indenting her code, but that's how she wrote all of her code.
Rod
March 22, 2015 at 9:42 pm
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, which is from one of the files in my "Hierarchies On Steriods".
CREATE PROCEDURE dbo.RebuildNestedSets AS
/****************************************************************************
Purpose:
Rebuilds a "Hierarchy" table that contains the original Adjacency List,
the Nested Sets version of the same hierarchy, and several other useful
columns of data some of which need not be included in the final table.
Usage:
EXEC dbo.RebuildNestedSets
Progammer's Notes:
1. As currently written, the code reads from a table called dbo.Employee.
2. The Employee table must contain well indexed EmployeeID (child) and
ManagerID (parent) columns.
3. The Employee table must be a "well formed" Adjacency List. That is, the
EmployeeID column must be unique and there must be a foreign key on the
ManagerID column that points to the EmployeeID column. The table must not
contain any "cycles" (an EmployeeID in it's own upline). The Root Node
must have a NULL for ManagerID.
4. The final table, named dbo.Hierarchy, will be created in the same will
be created in the same database as where this stored procedure is
present. IT DOES DROP THE TABLE CALLED DBO.HIERARCHY SO BE CAREFUL
THAT IT DOESN'T DROP A TABLE NEAR AND DEAR TO YOUR HEART.
5. This code currently has no ROLLBACK capabilities so make sure that you
have met all of the requirements (and, perhaps, more) cited in #3 above.
Dependencies:
1. This stored procedure requires that the following special purpose HTally
table be present in the same database from which it runs.
--===== Create the HTally table to be used for splitting SortPath
SELECT TOP 1000 --(4 * 1000 = VARBINARY(4000) in length)
N = ISNULL(CAST(
(ROW_NUMBER() OVER (ORDER BY (SELECT NULL))-1)*4+1
AS INT),0)
INTO dbo.HTally
FROM master.sys.all_columns ac1
CROSS JOIN master.sys.all_columns ac2
;
--===== Add the quintessential PK for performance.
ALTER TABLE dbo.HTally
ADD CONSTRAINT PK_HTally
PRIMARY KEY CLUSTERED (N) WITH FILLFACTOR = 100
;
Revision History:
Rev 00 - Circa 2009 - Jeff Moden
- Initial concept and creation.
Rev 01 - PASS 2010 - Jeff Moden
- Rewritten for presentation at PASS 2010.
Rev 02 - 15 Oct 2012 - Jeff Moden
- Code redacted to include a more efficient, higher performmance
method of splitting the SortPath using a custom HTally Table.
****************************************************************************/
--===========================================================================
-- Presets
--===========================================================================
--===== Suppress the auto-display of rowcounts to prevent from returning
-- false errors if called from a GUI or other application.
SET NOCOUNT ON;
--===== Start a duration timer
DECLARE @StartTime DATETIME,
@Duration CHAR(12);
SELECT @StartTime = GETDATE();
--===========================================================================
-- 1. Read ALL the nodes in a given level as indicated by the parent/
-- child relationship in the Adjacency List.
-- 2. As we read the nodes in a given level, mark each node with the
-- current level number.
-- 3. As we read the nodes in a given level, convert the EmployeeID to
-- a Binary(4) and concatenate it with the parents in the previous
-- level’s binary string of EmployeeID’s. This will build the
-- SortPath.
-- 4. Number the rows according to the Sort Path. This will number the
-- rows in the same order that the push-stack method would number
-- them.
--===========================================================================
--===== Conditionally drop the final table to make reruns easier in SSMS.
IF OBJECT_ID('FK_Hierarchy_Hierarchy') IS NOT NULL
ALTER TABLE dbo.Hierarchy
DROP CONSTRAINT FK_Hierarchy_Hierarchy;
IF OBJECT_ID('dbo.Hierarchy','U') IS NOT NULL
DROP TABLE dbo.Hierarchy;
RAISERROR('Building the initial table and SortPath...',0,1) WITH NOWAIT;
--===== Build the new table on-the-fly including some place holders
WITH cteBuildPath AS
( --=== This is the "anchor" part of the recursive CTE.
-- The only thing it does is load the Root Node.
SELECT anchor.EmployeeID,
anchor.ManagerID,
HLevel = 1,
SortPath = CAST(
CAST(anchor.EmployeeID AS BINARY(4))
AS VARBINARY(4000)) --Up to 1000 levels deep.
FROM dbo.Employee AS anchor
WHERE ManagerID IS NULL --Only the Root Node has a NULL ManagerID
UNION ALL
--==== This is the "recursive" part of the CTE that adds 1 for each level
-- and concatenates each level of EmployeeID's to the SortPath column.
SELECT recur.EmployeeID,
recur.ManagerID,
HLevel = cte.HLevel + 1,
SortPath = CAST( --This does the concatenation to build SortPath
cte.SortPath + CAST(Recur.EmployeeID AS BINARY(4))
AS VARBINARY(4000))
FROM dbo.Employee AS recur WITH (TABLOCK)
INNER JOIN cteBuildPath AS cte
ON cte.EmployeeID = recur.ManagerID
) --=== This final INSERT/SELECT creates the Node # in the same order as a
-- push-stack would. It also creates the final table with some
-- "reserved" columns on the fly. We'll leave the SortPath column in
-- place because we're still going to need it later.
-- The ISNULLs make NOT NULL columns
SELECT EmployeeID = ISNULL(sorted.EmployeeID,0),
sorted.ManagerID,
HLevel = ISNULL(sorted.HLevel,0),
LeftBower = ISNULL(CAST(0 AS INT),0), --Place holder
RightBower = ISNULL(CAST(0 AS INT),0), --Place holder
NodeNumber = ROW_NUMBER() OVER (ORDER BY sorted.SortPath),
NodeCount = ISNULL(CAST(0 AS INT),0), --Place holder
SortPath = ISNULL(sorted.SortPath,sorted.SortPath)
INTO dbo.Hierarchy
FROM cteBuildPath AS sorted
OPTION (MAXRECURSION 100) --Change this IF necessary
;
RAISERROR('There are %u rows in dbo.Hierarchy',0,1,@@ROWCOUNT) WITH NOWAIT;
--===== Display the cumulative duration
SELECT @Duration = CONVERT(CHAR(12),GETDATE()-@StartTime,114);
RAISERROR('Cumulative Duration = %s',0,1,@Duration) WITH NOWAIT;
--===========================================================================
-- Using the information created in the table above, create the
-- NodeCount column and the LeftBower and RightBower columns to create
-- the Nested Sets hierarchical structure.
--===========================================================================
RAISERROR('Building the Nested Sets...',0,1) WITH NOWAIT;
--===== Declare a working variable to hold the result of the calculation
-- of the LeftBower so that it may be easily used to create the
-- RightBower in a single scan of the final table.
DECLARE @LeftBower INT
;
--===== Create the Nested Sets from the information available in the table
-- and in the following CTE. This uses the proprietary form of UPDATE
-- available in SQL Serrver for extra performance.
WITH cteCountDownlines AS
( --=== Count each occurance of EmployeeID in the sort path
SELECT EmployeeID = CAST(SUBSTRING(h.SortPath,t.N,4) AS INT),
NodeCount = COUNT(*) --Includes current node
FROM dbo.Hierarchy h,
dbo.HTally t
WHERE t.N BETWEEN 1 AND DATALENGTH(SortPath)
GROUP BY SUBSTRING(h.SortPath,t.N,4)
) --=== Update the NodeCount and calculate both Bowers
UPDATE h
SET @LeftBower = LeftBower = 2 * NodeNumber - HLevel,
h.NodeCount = downline.NodeCount,
h.RightBower = (downline.NodeCount - 1) * 2 + @LeftBower + 1
FROM dbo.Hierarchy h
JOIN cteCountDownlines downline
ON h.EmployeeID = downline.EmployeeID
;
RAISERROR('%u rows have been updated to Nested Sets',0,1,@@ROWCOUNT)
WITH NOWAIT;
RAISERROR('If the rowcounts don''t match, there may be orphans.'
,0,1,@@ROWCOUNT)WITH NOWAIT;
--===== Display the cumulative duration
SELECT @Duration = CONVERT(CHAR(12),GETDATE()-@StartTime,114);
RAISERROR('Cumulative Duration = %s',0,1,@Duration) WITH NOWAIT;
--===========================================================================
-- Prepare the table for high performance reads by adding indexes.
--===========================================================================
RAISERROR('Building the indexes...',0,1) WITH NOWAIT;
--===== Direct support for the Nested Sets
ALTER TABLE dbo.Hierarchy
ADD CONSTRAINT PK_Hierarchy
PRIMARY KEY CLUSTERED (LeftBower, RightBower) WITH FILLFACTOR = 100
;
CREATE UNIQUE INDEX AK_Hierarchy
ON dbo.Hierarchy (EmployeeID) WITH FILLFACTOR = 100
;
ALTER TABLE dbo.Hierarchy
ADD CONSTRAINT FK_Hierarchy_Hierarchy FOREIGN KEY
(ManagerID) REFERENCES dbo.Hierarchy (EmployeeID)
ON UPDATE NO ACTION
ON DELETE NO ACTION
;
--===== Display the cumulative duration
SELECT @Duration = CONVERT(CHAR(12),GETDATE()-@StartTime,114);
RAISERROR('Cumulative Duration = %s',0,1,@Duration) WITH NOWAIT;
--===========================================================================
-- Exit
--===========================================================================
RAISERROR('===============================================',0,1) WITH NOWAIT;
RAISERROR('RUN COMPLETE',0,1) WITH NOWAIT;
RAISERROR('===============================================',0,1) WITH NOWAIT;
GO
The headers are crucial and always contain a purpose, usage, programmer's notes if needed, and revision history because all of that stuff can get lost if it's not in the code. It also keeps the next person from having to look all over hell's half acre to find information on it. They can even find where the original business requirements were by looking at the ticket (not included here for obvious reasons) identified in the Revision History.
Note that even sub-selects and CTEs are documented as to their purpose.
For those getting ready to whine about having to maintain the comments as well as the code, what's the problem with that? You know what your doing. Take the time to write it up. And it doesn't take long if the comments are written correctly.
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.
Better than that, I taught the Developers how to "really move" by using comments. Start off by writing the main sections of code as the "comment bars" with short descriptions as to what needed to be done between them. You can either do the whole proc that way at first or as you think of them over time. Then, write the shorter comments for each snippet of code that you intend to write. Then, do a quick review of your comments (almost like the block descriptions in a flow chart) and start peeling one potato at a time. Once each section is tested for functionality and, usually, performance, move on to the next section. You don't have to remember what you did or read code to figure out what you did because it's now quickly described in the comments and you already know it works. When you need to scroll up to the previous section to see something, it's real easy to tell where the previous section starts.
And, yeah... I really do write code like that for work and I really do have comments and code hints in the code. I usually even document non-obvious constants because I know what they are at the time I wrote them in the code and it will save someone later from having to look them all up. Takes me virtually no extra time to do.
I use a "river" style indent that's fairly unique, super easy to read, and easy (for me, anyway) to type. The only difference between the code above and my real code is that I very intentionally limited the code above to 77 characters in case someone wanted to print it or read it on the likes of a Kindle and to prevent (as much as possible) the need for horizontal scrolling/wrapping while reading the article on-screen. At work, I enforce the limit of 119 characters (stop when the column # = 120) for a couple of reasons.
1) It's bad enough to have to scroll vertically and a whole lot worse if you have to scroll horizontally so there's a limit on the number of horizontal characters.
2) If we do need to print the code out, we don't want wrapping to occur. With some of the ridiculously sized function names, the code needs to be wide enough to remain vertically dense enough to prevent the need for a lot of unnecessary vertical scrolling. I decided on exactly 119 characters because if you set 1/2 inch margins, the landscape mode, and very readable 10pt Courier New or 10pt Lucida Console (both fixed width fonts), you can fit exactly 119 characters on the paper without wrapping. I also insist on some reasonable form of indentation especially on seriously complicated formulas that may require much more than 119 characters.
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.
--Jeff Moden
March 22, 2015 at 9:52 pm
Jeff Moden (3/22/2015)
To me, it's simple and I train the Devs and DBAs that I work with on two very simple concepts.
Isn't training Devs akin to training cats? Not sure about DBAs.
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 22, 2015 at 10:03 pm
dwain.c (3/22/2015)
Jeff Moden (3/22/2015)
To me, it's simple and I train the Devs and DBAs that I work with on two very simple concepts.Isn't training Devs akin to training cats? Not sure about DBAs.
Not if they're good Developers especially when it comes to the concept of doing it right the first time. We have a simple but very effective interview process and we won't take someone on just because we need a body if they "don't fit". And, no... HR doesn't get involved with our interview process until we hire someone.
--Jeff Moden
March 23, 2015 at 8:29 am
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?!!!
-----
[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 24, 2015 at 2:08 pm
I worked on a project we just about every program had a comment in it which read
// Jim QQQ is a moron
Jim QQQ was a'programmer' whose brother owned the company.
I thought this commenting was ridiculous, until I met Jim QQQ. It was both a comment about the code and a warning.
BTW, that contract was short lived...
March 24, 2015 at 2:45 pm
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??
😎
March 24, 2015 at 3:05 pm
The worst comments are where someone has /* commented */ out blocks of code, sometimes pages and pages, with no explanation for when or why.
"Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho
March 24, 2015 at 3:09 pm
Eric M Russell (3/24/2015)
The worst comments are where someone has /* commented */ out blocks of code, sometimes pages and pages, with no explanation for when or why.
Makes one think of the processes in place, how would such a code pass any review?
😎
March 24, 2015 at 4:22 pm
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. 😀
--Jeff Moden
March 25, 2015 at 3:08 am
Too modest Jeff. 🙂
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
March 25, 2015 at 3:42 am
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.
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 25, 2015 at 6:09 am
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.
Viewing 15 posts - 91 through 105 (of 156 total)
You must be logged in to reply to this topic. Login to reply