So, in my day job, I had a Subject Matter Expert (SME) come up to me and ask me to change a business rule on how data gets presented to the user on a web page. Being the good project manager that I am, always trying to please the client.. I tell her Sure, I'll get right on that.
So I fire up the solution and go to the page in question, then determine which one of the 7 data access methods in this system (that's a story for another day) that this particular page uses to get it's data, and proceed to the stored procedure in question.
1321 lines in this proc. Yes, One Thousand, Three Hundred and Twenty One.
Entire Blocks of T-SQL code are commented out, with no explanation as to why, the reason it was done, or when it was done.
The parts of code that are "properly" commented are littered with comments such as "???" and "RJPOS" and "have to do this too!". So I have unreadable comments commenting code, which is totally useless to all developers, including the one that placed the comment there in the first place. I guarantee that if I handed this code to the person who made the "???" comments six months from now, he will have no idea what his intention was.
That's my point. If you can't leave a comment that will stand the test of time, don't leave a comment at all. Erroneous comments will only serve to confuse those who have to maintain your spaghetti code crap in the future.
Here's another pet peeve of mine: --"or ses_missing = 1" no longer a condition
If that piece of code or criteria is no longer a condition, then remove it from the proc all together. Having that as a comment does nothing for the current readability of the code, and only serves to litter it up with green text.
Don't get me wrong... I am a firm believer in commenting your code. Please do. Good quality comments will not only serve to make your life easier six months or a year from now, but it will also serve to make those who have to clean up after you as well.
Code Commenting Guidelines:
- Write comments that stand the "test of time". That is to say, write comments that are meaningful to the execution of a particular code block who's purpose is not readily forthcoming by examining the code itself.
- If the purpose of a block of code is not readily apparent from simply examining it, then consider refactoring that block of code to make it more readable. If that's not possible, refer to guideline 1.
- If a block of code is invalidated, do not comment it, remove it.
- Code Commenting is *NOT* a replacement for proper code formatting!!
The long and short of it is.. Comment your code properly... But if you can't comment your code properly, then for the love of all that is holy, don't comment at all!
Edit: With properly formatting the code, and removing all the "extraneous" comments, the line count is down to 608.