A job, like any thing in life, is very much an up and down, give and take. Some weeks, I get to send emails like this (and I did):
Hey man, you wrote xyzProcedure back in march (so the proc says), and I just wanted to say thank you for using comments. It’s so much easier to develop on the back of others’ code if there’s a little explanation, and comments are something of a lost art.
And then there are weeks where every procedure I open up looks like this:
CREATE PROCEDURE [dbo].[GetWidgetList] ( @StoreID INT = NULL ) AS — ============================================================================== — Author: Star Team — Create date: 01/12/2009 — Description: Get Widget List — ============================================================================== SET NOCOUNT ON IF @StoreID IS NOT NULL BEGIN –< insanely complicated code without comments here > END RETURN 0 ;
Oh, really? Really?? I mean, nice use of commented seperation bars, and thank GOD I know when the frigging SP was written, but really? It was written by the entire Star Team, not by an individual or group of individuals…in other words, anyone I could go to and ask for assistance, information, intelligent banter. The description is the procedure name, with spaces (for readability!) And I have 3 zillion lines of IF/THEN/ELSE/nested CURSOR code without a single useful comment, unless you count the aged out code that you've commented out instead of deleting.
Go aheady, kick my dog already. Pour gasoline on my flowers. Knock me down, steal my car, drink my liquor from the old fruit jar, but honey, put in some blue suede comments. Here's a nice little example:
CREATE PROCEDURE [dbo].[GetWidgetList] ( @StoreID INT = NULL ) AS — ============================================================================== — Author: Jen McCown, Star Team. — Email jen@jennifermccown.com — Cel 123-456-7890 — Office 123-456-9874 — Create date: 01/12/2009 — — Defect: CR6189 — — Description: This procedure retrieves a list of active widgets for a — particular store, along with configuration data from the Preet table. — Note that if a widget has been aged out but is still active, it is — displayed but marked as "moronic"; the Zeet users like this, but for the record — it tends to confuse the BAs. Refer them to the WidgetBizRules document on — Star Team sharepoint (url…). — — Return 0 – completed without errors. — Return 1 – storeID does not exist — … — ============================================================================== SET NOCOUNT ON ——————————- — Check for existing StoreID ——————————- IF @StoreID IS NOT NULL BEGIN ——————————- — section 1: declare & variables ——————————- –< nice code with comments > ——————————- — section 2: get config settings — Notes blah blah blah… ——————————- –… END RETURN 0 ;
Go thou and SIN NO MORE.
-Jen McCown, http//www.MidnightDBA.com