January 5, 2009 at 12:26 pm
When it comes to documentation, i am one of those that errs on the side of too much; and that's saying a lot. Having worked in the field for 15 years, I have had a variety of positions where I have had to spend way too long figuring out someone else's code techniques and the why's and wherefores of the approach (often by mistakenly attempting to 'fix' apparent inconsistencies or inefficiencies only to have to fall back on the original methodology). Documentation is for you, for your support teams, but most of all for your successors. The worst way to waste money on contractors is to hand them undocumented work to complete. In teaching, I always looked for and effusively praised people who documented their exercises. I just consider the programming community better served by well documented code.
Remember, you will move on, but your code will remain, as will your repuatation. Good documentation keeps YOU from being the broken link and the cursed name in someone else's bad day.
KT
😎 Kate The Great :w00t:
If you don't have time to do it right the first time, where will you find time to do it again?
January 5, 2009 at 12:28 pm
GSquared (1/5/2009)
If you set a standard that the variable "i" (or @i) is only to be used for while loops, and is to be used for all while loops, and if you need more than one while loop you use "i1", "i2", etc., and no other variables are to have that format except while loops, then when you see an "i" in your code, you know it's a while loop.
i1, i2, etc, ick. That's one of the things I changed when I changed my coding style to be more readable. Generally I use i for any iteration variable, but if I ever need to use more than one in the same scope I use i prefixed to a name for all iteration variables and don't use i by itself. So I might have iPayPeriod, iFiscalYear, etc. The i prefix retains the familiar i naming scheme and the name conveys exactly what it's iterating. I've found that especially helpful for loops inside of loops when trying to read code and figure out what i, j, k, etc represented. (I tried using names like iInner and iOuter in the beginning but found they didn't work any better than using j and k. :P)
January 5, 2009 at 12:40 pm
I believe in "detailed" documentation. Not writing it for any level, so I guess you are writing it for all levels.
It is soooooooo much easier to read a document, look at the code, process, etc. and make sense of it. Rather than having to decipher line by line what someone else did.
We all think differently; we all write differently; etc. etc. And if it accomplishes the same task without killing the system. All of it, in my view point is correct even though different.
January 5, 2009 at 12:46 pm
Steve Jones - Editor (1/5/2009)
Are you complaining about BOL? It's definitely lacking in places, but it's a pretty good document and I love the ability to give back feedback or add community links. Definitely a good step forward....
I too love BOL BUT...., it along with all of Microsoft's Knowledge items that use the Document Explorer shell, need to include teh ability to do markups and do so on a users local copy or their companies copy and not be restcrted to Microsoft's web based version they host.
Kindest Regards,
Just say No to Facebook!January 5, 2009 at 2:53 pm
fuller.artful (1/5/2009)
In my early days, I was a "cowboy coder". I learned my lessons. Now I write a comment header for every module before I write a single line of code, describing what the module is expected to accomplish, what its input parameters are and what its outputs are. I go further than that, too, with inline comments about what a particular While loop is intended to do, and so on.
The problem I would have is that my design changes as I'm coding an application and therefore the comments keep changing. I usually wait until I'm done or almost done before writing inline comments. Then I try to be robust with them.
Eric Klovning (1/5/2009)
A brief prose document along with inline comments provide a basic overview and aren’t too difficult to create and maintain.Anything more detailed is not worthwhile unless an established process exists to update and distribute the documentation as system changes are made.
Well said. Why bother to create this nice documentation outside the system if someone else doesn't know to go look at it anyway? And if we're filling in for somebody it's we're often because the darn thing stopped working or we're trying to get some quick answers. Not sure that I want to look at too many external pages. But I can appreciate some good inline, up to date comments.
Ken
January 5, 2009 at 3:12 pm
I think you need a good guide to a code product and good function/procedure level documentation. I believe inline documentation and quality code are intertwined - if you have a ton of inline comments you're either over-documenting or you haven't structured your code well. I only use inline when necessary and when it happens it is a chance to review my design to see if there is a simpler way. If not, the inline comment stays.
I'm still learning the value of documentation, but having recently passed on 6 years of knowledge to junior resources in a prior job successfully I've learned a few things:
Hire character over skills. A certain level of skill is necessary, but a genious who doesn't really care is much worse than a slightly underqualified person with a good work ethic and a desire to succeed. You can document the entire world and it won't matter to the wrong person regardless of skill or experience.
A junior resource needs to know what the system is doing, how to find the components that get it done and a description of what those components do. If they need any more documenation than that then either the system design is too complex, the wrong person is maintaining it or both.
January 6, 2009 at 3:15 am
I once read
"Documentation is like sex. When it is bad, it is still better than none at all.:D"
January 6, 2009 at 3:57 am
When you write documentation and only then the code you are not writing it twice - the code should be a translation of the documentation. I have been coding for (gulp!) over forty years, and I have found (the hard way) that comments are worth their weight in platinum.
I find now that I write nearly twice as much comment (and background documentation) as I do code. It's not anal - it's forward thinking.
January 6, 2009 at 6:35 am
Ian Kelly (1/6/2009)
When you write documentation and only then the code you are not writing it twice - the code should be a translation of the documentation. I have been coding for (gulp!) over forty years, and I have found (the hard way) that comments are worth their weight in platinum.I find now that I write nearly twice as much comment (and background documentation) as I do code. It's not anal - it's forward thinking.
32 years of coding here, and I say *amen brother*. 🙂 Comments are the ONLY guidelines you have when you're trying to figure out the mindset of the author. Their coding technique only tells you so much.
January 6, 2009 at 9:35 am
My personal take on this is: Less is more. Unless the code is obtuse or makes calls to third-party libraries, the code speaks plainly enough for itself. Often, when I am trying to read another's code, I delete the comments (from a separate copy, of course) to allow the code to flow more smoothly.
January 6, 2009 at 9:36 am
Timothy (1/5/2009)
GSquared (1/5/2009)
If you set a standard that the variable "i" (or @i) is only to be used for while loops, and is to be used for all while loops, and if you need more than one while loop you use "i1", "i2", etc., and no other variables are to have that format except while loops, then when you see an "i" in your code, you know it's a while loop.i1, i2, etc, ick. That's one of the things I changed when I changed my coding style to be more readable. Generally I use i for any iteration variable, but if I ever need to use more than one in the same scope I use i prefixed to a name for all iteration variables and don't use i by itself. So I might have iPayPeriod, iFiscalYear, etc. The i prefix retains the familiar i naming scheme and the name conveys exactly what it's iterating. I've found that especially helpful for loops inside of loops when trying to read code and figure out what i, j, k, etc represented. (I tried using names like iInner and iOuter in the beginning but found they didn't work any better than using j and k. :P)
I'm just using that as an example of "Standards as Documentation". I don't use single-letter variables, nor table aliases. In proof-of-concept code, I will use #T for a temp table, but only because I'm too lazy to come up with something more imaginative for a single-use temp table that will never be seen by anyone ever again.
- Gus "GSquared", RSVP, OODA, MAP, NMVP, FAQ, SAT, SQL, DNA, RNA, UOI, IOU, AM, PM, AD, BC, BCE, USA, UN, CF, ROFL, LOL, ETC
Property of The Thread
"Nobody knows the age of the human race, but everyone agrees it's old enough to know better." - Anon
January 6, 2009 at 9:40 am
Here, here, rootman!
January 6, 2009 at 1:19 pm
There are other people that will look at the documentation as well. The client and management. Neither of them are expected to know anything about databases, so detailed documentation is a must. Without it, I am certainly going to hear about it and have to explain why I was not detailed in my docs.
January 6, 2009 at 2:04 pm
John Hick (1/6/2009)
My personal take on this is: Less is more. Unless the code is obtuse or makes calls to third-party libraries, the code speaks plainly enough for itself. Often, when I am trying to read another's code, I delete the comments (from a separate copy, of course) to allow the code to flow more smoothly.
You must be using something other than Dot NET then. It allows you to "collapse" the comments. Best of both worlds.
I have coded in both the open-source and closed-source worlds. PERL, PHP, MySQL, Oracle, and most of the MS line. I have used Notepad, VII, UltraEdit32, Zend, Eclipse, and other editors, along with the MS line. Nothing rocks more than a flexible development environment. (No war with any here, just the search for the environment with the most frills as you can use almost any of them to code any language with certain upgrades).
I happen to prefer the Dot Net environment. I have my reasons.
I have learned the hard way to document as much as possible. There are tools out there that can read the comments out in to a technical doc, especially if you abide certain documentation standards (like XML comments).
Ten years ago, it did not seem useful to me, but build a significant project while documenting along the way, and hand both the project and a full technical description to the customer... I have had blazing reviews for such things... "We never expected this!" (in very incredible but happy overtones). It didn't cost extra, and comes second nature to project planning. Write procedure shells, document them, and then start coding. You will iron out more potential bugs in the first round of code, and allow a framework that anyone else can sit and help code, because the documentation on what is expected is already there. It is an extremely reduced distance between plan and execute. It also allows that significant overhauls are easier when you need to assess affected portions.
The documentation is NOT for you, at least not at first, but in a big project that spans years, it will be eventually...
Documenting almost never hurts you, and more often than not, helps you to look very good. Not documenting, on the other hand, can kill a project, or bring on assumptions of "spaghetti code" even when it is not. Coders will argue as far as the day is long on what is better coding, better language, better methodologies. However, show one with a documented project against one that is not, and in the first there is found a coder who will be viewed as being worth their pay because at the very least they were able to articulate what the intent was, while the second one is usually getting verbally abused long after they are gone.
January 7, 2009 at 8:04 am
unfortunately the shop i am in feels that documentation is not necessary. They feel that it is to costly to write any technical documentation other than the end user guides. Unfortunately this means that they do not notice some large issues as they document that we find later in life. Spending a few hours on the front end will save weeks on the back end.
Has anyone be able to put a ROI on their documentation as it progressed to be more thorough?
I can understand that deadlines and cost is important however i feel that longevity and supportability are equally if not more important. Anything that i do i ensure that there is enough documentation around what i want to accomplish and what the process flow is so that people can follow it if they inherit it or i get hit by a bus.
Viewing 15 posts - 31 through 45 (of 89 total)
You must be logged in to reply to this topic. Login to reply