May 14, 2015 at 12:00 am
Comments posted to this topic are about the item Documenting with Tests
May 14, 2015 at 2:04 am
The only issue I have documentation is that a piece of paper doesn't know what the code does. I have run into documentation, schedules, in-line comments all saying the opposite than what the actual code does. How many of us comes across an index that has a name the is misleading?
Documentation can help but writing clear code, I believe, helps even more.
May 14, 2015 at 6:42 am
Notes Scribbled on paper <> Novel
Code Comments <> Documentation
Just in case that was not clear to everyone already.
May 14, 2015 at 6:46 am
Yet Another DBA (5/14/2015)
The only issue I have documentation is that a piece of paper doesn't know what the code does. I have run into documentation, schedules, in-line comments all saying the opposite than what the actual code does. How many of us comes across an index that has a name the is misleading?Documentation can help but writing clear code, I believe, helps even more.
This is a great point.
Naming conventions are real! Using them properly can make the code be the documentation.
May 14, 2015 at 7:29 am
The best piece of documentation I ran across recently was something I wrote in the code back in 2002. It said something about the code being modified as per Board Action and the date. I was able to show that comment to justify why the code was acting the way it was. It proved that the one saying the app was not functioning correctly was wrong. If worked just the way the Board wanted it to work.
May 14, 2015 at 8:00 am
Some unit tests are derived from high level assertions (ie: each active sales person should be assigned to at least one but no more than three sales regions), and these type of assertions should be documented on paper and not just communicated at a status meeting or by email.
Other unit tests are basically for smoke testing and performed by the database developer. For example, a stored procedure that creates a new sales order may have a unit test that simply queries an account number, an active sales person, 10 products, then builds up a set of input parameters, calls the stored procedure, and finally queries the Order related tables to verify that the expected records were inserted. When I write a procedure, I'll include one or two unit tests within the header comments or if it's complicated, then I'll place it all within a commented section at the bottom.
Other unit tests are integration tests done through the application. That is typically a series of steps documented on paper and performed by a QA engineer.
"Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho
May 14, 2015 at 8:19 am
I like to put comments in all my code. If the code I am writing is not obvious as it's intent and I can explain in a sentence or two I enter comments. A lot of time it helps me remember why we did something a particular way so it is as much for me as anyone else.
We also use them as an audit trail for changes made to procedures, functions and views. Example below:
--<5> 5/14/2015 - Add join to Item table to include Items description
INNER JOIN Item I --<5>
ON I.ItemNumber = D.ItemNumber --<5>
May 14, 2015 at 12:08 pm
PHYData DBA (5/14/2015)
Code Comments <> DocumentationJust in case that was not clear to everyone already.
I have to strongly disagree with that if it's done correctly. The next question would be "when has it ever been done correctly"? The answer is "In every damned piece of code written in my shop because I enforce it with a set of written standards. 100% peer reviews, and 3 band pork chop launcher". 🙂
--Jeff Moden
Change is inevitable... Change for the better is not.
May 14, 2015 at 12:16 pm
I think Jeff is right in that coding comments can be good documentation. They might not be all you want, but they can cover things from the tech perspective. Whether that works for the business is something else.
May 14, 2015 at 12:26 pm
Jeff Moden (5/14/2015)
PHYData DBA (5/14/2015)
Code Comments <> DocumentationJust in case that was not clear to everyone already.
I have to strongly disagree with that if it's done correctly. The next question would be "when has it ever been done correctly"? The answer is "In every damned piece of code written in my shop because I enforce it with a set of written standards. 100% peer reviews, and 3 band pork chop launcher". 🙂
Is it comments in the code or are you're standards, naming conventions, and the Pork chop launcher that make this true?
I worked on an app that was very well written and the code comments in the stored procedures were wonderful.
They could never detail or inform anyone of how they were used by all the applications and services that executed them.
If we did not have that documentation it would have been am impossible and life stealing task to determine how everything worked together.
Code comments are great but they are what I would consider part of the documentation not all of it.
May 16, 2015 at 5:43 am
I personally love SQL Prompt for comments in my code. I love JIRA/Confluence for build management and documentation of my environment that's accessible to the entire team.
I forget what amazing DBA I snagged my code comment template from, but I use a template for comment blocks that outlines a great header that entails a summary of my code page. Then I use individual comment blocks, which include my user with history, throughout every section. I then use single line comments to further explain each section of the query.
My main goals when commenting in code is to introduce the end user to the code as if they have never seen it before, get them up to speed on who has last touched the code with a change history, give them some example use cases of the code they are about to edit, explain each section with a decent high-level summary and then walk them through each major focal point of the code with some explanation of the design.
Doing this requires extra time on my end, but I feel the time spent is worth it, especially for the next guy who may replace me in case of fire. 😉
May 17, 2015 at 10:32 am
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.
May 18, 2015 at 3:43 am
My personal bugbear is that IT sectarianism rears its ugly head when it comes to commenting code. There are hard core polarised views held by noisy evangelists and a quiet block of pragmatists in the middle.
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.
I have been experimenting with Cucumber/Gherkin and the language of the tests constitute a catalogue of the requirements that are readable by a non-technical person at a level that enables them to say "Yes, that is what I want".
I haven't had time to dig deeper in the .NET world but I believe that SpecFlow allows a similar approach.
The idea of the Gherkin language is that it is programming language agnostic. If you ported your app to another programming language then the tests would stay the same, it would be the implementation language that would differ. It's worthy of further investigation.
When I look at code with a good test coverage then what I have is a good catalogue of requirements for the code. This is not to be sniffed at, it is to be treasured for the rarity it is. Although a significant piece it is only one piece in the documentation jigsaw.
I learnt to programme by typing in listings published in magazines. The programmers who submitted those listings supplied comments and wrote the article around their code
with a view to educating the next generation of programmers. For that reason I view code comments as a means of educating the next generation. We have a plethora of tools such as JavaDoc that can scrape structured comments from code and publish them. Instead of railing against code comments I think the "source code is the only documentation" crowd would be best figuring out how best to capitalise on the tools available to keep documentation to a useful and pragmatic minimum.
May 18, 2015 at 5:36 am
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.
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
May 18, 2015 at 7:10 am
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.
"Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho
Viewing 15 posts - 1 through 15 (of 26 total)
You must be logged in to reply to this topic. Login to reply