May 18, 2015 at 8:38 am
Gary Varga (5/18/2015)
It's probably unlikely that you ever found much value in the comments in a paying job.
So untrue.
The key in code comments are what gets commented. You shouldn't document what the code does (the code does that) but what the intent is at a higher level of abstraction. You shouldn't document the system architecture as then it would be repeated, spread all over the place and unmaintainable (an external document is best suited for this).
Unit tests define and document the minutiae of implementation decisions that would otherwise exist in defect management systems, emails and (please no) spreadsheets. They are an excellent way to document this information whilst avoiding the reintroduction of faults. And, yes you can comment unit tests.
Tests which are formally agreed are often referred to acceptance tests and should be treated differently from unit tests EVEN if they are developed alongside unit tests using the same technology.
I once worked with someone who truly believed that by naming alone you could comment a system. I don't care how well functions, procedures, methods, classes, variables, properties, files, etc. are named they do not cover intent. They document what the code does. Sometimes very well. Needless to say, this individual's code was a nightmare to maintain and he was considered a "hero" by his employer. Suckers.
Agreed, with one small refinement. To the same extent that your comments should describe the intent rather than every individual step along the way, the tests can provide solid insight into the function if you provide the INTENT of the test, not the actual test. Formally - if you describe the test declaratively (if you want to go 100% formal, use pre-/post-conditions), but not the raw test. Tests often have lots of "junk" used to set up and tear down the test scenario, which will cloud the documentation aspect. For example - I've had to create temporary structures, but some kind of data into them, fire a procedure against it and then run some very specific queries to check if the output is what I'd expect. You might end up with a couple of pages worth of code, where the "test" is buried somewhere in the middle.
----------------------------------------------------------------------------------
Your lack of planning does not constitute an emergency on my part...unless you're my manager...or a director and above...or a really loud-spoken end-user..All right - what was my emergency again?
May 18, 2015 at 1:38 pm
David.Poole (5/18/2015)
We must not lose site of why documentation should be written. It is to impart useful knowledge to the poor sod who will end up maintaining your code....and sometimes that poor sod will be you! I have come across notes and comments in code that made perfect sense at the time I wrote them and a year later keep me awake at night wondering what I meant.
Very true. A good reason to learn to write for a time when you won't be immersed in the code. I wish I had a good technique here, and it's one reason I try to re-think about comments when I come across one I've written that doesn't make sense.
The idea of language agnostic comments is interesting. Certainly, if you have unit tests they should work, no matter how the method/function/etc is written and runs later.
May 18, 2015 at 1:39 pm
Gary Varga (5/18/2015)
It's probably unlikely that you ever found much value in the comments in a paying job.
So untrue.
The key in code comments are what gets commented. You shouldn't document what the code does (the code does that) but what the intent is at a higher level of abstraction. You shouldn't document the system architecture as then it would be repeated, spread all over the place and unmaintainable (an external document is best suited for this).
You've pulled context out of the quote. I was speaking about the comments that professors far too often are expecting. Some kind of silliness that would explain the code to your 8 yr old sibling.
May 18, 2015 at 1:40 pm
Eric M Russell (5/18/2015)
When initially creating a stored procedure, I'll sometimes copy / paste text from the functional specification into the header comments.Also, it helps to include the RFC# or equivalent when commenting code changes going forward.
If your requirements documentation and dataflow diagrams are in SharePoint, TFS, or something like that, then go ahead and include hyperlinks in the header as well.
That's interesting, assuming you have a good URL. I do like the idea of a functional spec, perhaps with a link out to some document name (Which can be searched if your file server/sharepoint/whatever, moves.)
May 19, 2015 at 7:05 am
Steve Jones - SSC Editor (5/18/2015)
Gary Varga (5/18/2015)
It's probably unlikely that you ever found much value in the comments in a paying job.
So untrue.
The key in code comments are what gets commented. You shouldn't document what the code does (the code does that) but what the intent is at a higher level of abstraction. You shouldn't document the system architecture as then it would be repeated, spread all over the place and unmaintainable (an external document is best suited for this).
You've pulled context out of the quote. I was speaking about the comments that professors far too often are expecting. Some kind of silliness that would explain the code to your 8 yr old sibling.
Sorry. My bad. I misread your intended point.
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
May 19, 2015 at 2:52 pm
Gail Wanabee (5/17/2015)
I've worked in shops where formal documentation was required for all code and it had to be maintained.I've worked in shops where developers insisted that the best and only documentation required is the source code itself.
I contend that somewhere between these 2 extremes lies rationality and practicality. What has worked for me is a hybrid of the 2.
___________
Unless some code I'm working on is extraordinarily simple, I usually either write or type a brief outline of the most important code steps. This “documentation” is then copied and pasted into my development window and I code for and under each documented code step, embellishing where I must for clarity and to justify code steps for which my rationale might not be obvious to someone in a support role, examining my code later. And of course, good naming conventions in the source code always assist with the documentation.
This method has a few advantages over other methods:
1.The code and its documentation are both contained in the source code document.
2.If the code is changed, its supporting documentation can be easily changed in the same document at the same time.
3.The documentation is not overly lean or fat.
4.The documentation directly supports the implementation and vice-versa.
Yes! This! All of this!
May 19, 2015 at 4:57 pm
PHYData DBA (5/19/2015)
Gail Wanabee (5/17/2015)
I've worked in shops where formal documentation was required for all code and it had to be maintained.I've worked in shops where developers insisted that the best and only documentation required is the source code itself.
I contend that somewhere between these 2 extremes lies rationality and practicality. What has worked for me is a hybrid of the 2.
___________
Unless some code I'm working on is extraordinarily simple, I usually either write or type a brief outline of the most important code steps. This “documentation” is then copied and pasted into my development window and I code for and under each documented code step, embellishing where I must for clarity and to justify code steps for which my rationale might not be obvious to someone in a support role, examining my code later. And of course, good naming conventions in the source code always assist with the documentation.
This method has a few advantages over other methods:
1.The code and its documentation are both contained in the source code document.
2.If the code is changed, its supporting documentation can be easily changed in the same document at the same time.
3.The documentation is not overly lean or fat.
4.The documentation directly supports the implementation and vice-versa.
Yes! This! All of this!
Ditto that.
--Jeff Moden
Change is inevitable... Change for the better is not.
May 24, 2015 at 6:42 am
How do you do unit tests in T-SQL?
Rod
May 24, 2015 at 12:01 pm
Doctor Who 2 (5/24/2015)
How do you do unit tests in T-SQL?
Try http://www.red-gate.com/products/sql-development/sql-test/
It is possible to devise your own method of initialising a starting set of data, executing your stored procs and then comparing them to expected output throwing errors if the results are other than as expected. The Red-Gate sql-test product just makes it much easier and intuitive to do so.
May 24, 2015 at 12:17 pm
Doctor Who 2 (5/24/2015)
How do you do unit tests in T-SQL?
Go to tsqlt.org to get a framework. There are others, like dbunit, tsqlunit, etc., but I like tsqlt.
We have articles here:http://www.sqlservercentral.com/articles/tSQLt/
May 24, 2015 at 6:38 pm
David.Poole (5/24/2015)
Doctor Who 2 (5/24/2015)
How do you do unit tests in T-SQL?Try http://www.red-gate.com/products/sql-development/sql-test/
It is possible to devise your own method of initialising a starting set of data, executing your stored procs and then comparing them to expected output throwing errors if the results are other than as expected. The Red-Gate sql-test product just makes it much easier and intuitive to do so.
Thank you, David.
Rod
May 24, 2015 at 6:38 pm
Steve Jones - SSC Editor (5/24/2015)
Doctor Who 2 (5/24/2015)
How do you do unit tests in T-SQL?Go to tsqlt.org to get a framework. There are others, like dbunit, tsqlunit, etc., but I like tsqlt.
We have articles here:http://www.sqlservercentral.com/articles/tSQLt/
Thank you, Steve.
Rod
Viewing 12 posts - 16 through 26 (of 26 total)
You must be logged in to reply to this topic. Login to reply