Click here to monitor SSC
SQLServerCentral is supported by Red Gate Software Ltd.
Log in  ::  Register  ::  Not logged in
Home       Members    Calendar    Who's On

Add to briefcase 12345»»»

A Dearth of Comments Expand / Collapse
Posted Sunday, January 4, 2009 10:02 PM



Group: Administrators
Last Login: Today @ 1:18 PM
Points: 32,695, Visits: 16,993
Comments posted to this topic are about the item A Dearth of Comments

Follow me on Twitter: @way0utwest

Forum Etiquette: How to post data/code on a forum to get the best help
Post #629576
Posted Monday, January 5, 2009 2:02 AM

SSC Eights!

SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!

Group: General Forum Members
Last Login: Wednesday, November 4, 2015 2:41 AM
Points: 919, Visits: 364
It's definitely the easy way out for developers to skip (or skimp) documentation. It's like the seventh red-haired (step) child that nobody likes because it sticks out so much, takes so much time, takes away time from "true" work and is almost always considered an after thought once a project finished.

On the other hand a truelly well documented project is a treasure trove for developers - junior especially. With developers I mean not only the ones that have this title but all people who develop code on a regular basis - which includes most DBAs.

While senior developers most often use the in-code documentation to find out what their colleague intended to do to understand, replicate, improve the code for junior developers it is a first step to better programming. Certainly for me without the good in-code documentation I wouldn't be able to learn as fast on my own as I did over the last few years. A few lines more saved me countless hours of trying to figure out why.
This is especially true in my current job where I picked up from another developer - and his code was just the code with about 1 line documentation for 1000 lines of code. Without his comments (he luckily still works in the team) deciphering what certain lines of code do would have been difficult at least.
So as a start we did a drive to at least document our code base. Three weeks later this was done and proved fortunate when a new developer started in our team. Very much on the junior side he learned code pretty much from the comments within and the header at the start of the code explaining in a single sentence what the code was about and additional notes where things are not as clear as they could be. This developer has learned very well within three months and is now able to code fairly proficient and avoided a lot of beginner mistakes.

In addition (mainly because we code for a complex data warehouse project) we have additional documentation of how, why, what and where our project works. This is at a high level describing why we take what data from which server to achieve results, what can go wrong and how to rectify this. Granted, for the developers who work with this on a daily basis this is mainly in their heads and second nature.
For me this documentation was very good to have when I started and my estimate is that it saved me about 6 months poking through code and asking lots of questions and allowed me to understand my new job within a week. Where the documentation was not helpful I asked the right questions (and some dumb ones) and amended it.
So again this documentation helped the next new developer to understand within a week what his job is all about along with on-the-job training.

While such documentation is considered most often "wasted time" from the point of view of a new job start I can only recommend doing it. It may not help you directly but it will certainly help someone in the future (a lot). In addition during my last interview round I found that managers appreciated the level of documentation I had for my last system and it was certainly one of my strengths that landed me my current job.

Another area that developers try to avoid like satan the holy water is writing a manual. Granted, most of them are quite rubbish with it and most of them are down to a tick list of do this, then do that, then do the next.
While this provides a rough guide how to work a system I found that a bit of background information (about a page long max) helps users not only to do the job but take ownership of it too.
For example I recently had to develop a simple upload of an Excel file into a database. Basic instructions aside there was a quick description of how the system achieves this and some error descriptions. This pretty much saves me about 2 hours each month trouble shooting. Because the user understands what they need to check and they can do it for themselves.
All this for about 1 hour work writing the manual.

In my previous job a project was considered finished, when the helpdesk support told the manager that they have adequate documentation to support a new system. One particular developer had a project going on for six years taking about 3 to 6 hours each week away that he had to dedicate to support - simply because he hated writing documentation.

So for all developers who really really don't like to do documentation my advice is to do at least adequate in-code documentation (that means a header and lines for particular tricky stuff) and about 3 to 4 pages of what a system does at a high level. If required, put in some notes for the manual where and why things can go wrong.
This way when helpdesk (or a user) calls just tell them to look up the documentation (preferably on the Intranet) and call back if that doesn't answer the question.

That way allows you to spend more time on the perk of each development job.
Post #629629
Posted Monday, January 5, 2009 3:04 AM



Group: General Forum Members
Last Login: Tuesday, November 24, 2015 8:02 AM
Points: 173, Visits: 1,802
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.

Post #629646
Posted Monday, January 5, 2009 5:18 AM
SSC Rookie

SSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC Rookie

Group: General Forum Members
Last Login: Friday, March 8, 2013 10:18 AM
Points: 47, Visits: 165
As for me, I am heavily on the side of thorough documentation, updated always before any revisions are undertaken. My view is that the logic is contained in the documentation, and when it's correct, it's relatively simple to write the code that implements it.

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 in-line comments about what a particular While loop is intended to do, and so on.

Call me anal-retentive if you wish, but I tend to operate on the principle that I may be killed by a truck on the way to work tomorrow morning, and my replacement ought to have as much information as possible.


Arthur Fuller
cell: 647-710-1314

Only two businesses refer to their clients as users: drug-dealing and software development.
-- Arthur Fuller
Post #629693
Posted Monday, January 5, 2009 6:34 AM



Group: General Forum Members
Last Login: 2 days ago @ 9:11 PM
Points: 10,681, Visits: 14,286
I guess I disagree with Steve a little on this one as I believe that documentation/comments should be written so someone below your level can understand the code. I worked for/with an excellent developer who did not document well and know I am back as a contractor working on his code and it is taking 2 or 3 times as long to debug because the lack of documentation or because of documentation that was never updated as code and processes were changed.

I know that documentation and commenting is a weak area in my coding as well and I am trying to get better at it.

Jack Corbett

Applications Developer

Don't let the good be the enemy of the best. -- Paul Fleming
At best you can say that one job may be more secure than another, but total job security is an illusion. -- Rod at work

Check out these links on how to get faster and more accurate answers:
Forum Etiquette: How to post data/code on a forum to get the best help
Need an Answer? Actually, No ... You Need a Question
How to Post Performance Problems
Crosstabs and Pivots or How to turn rows into columns Part 1
Crosstabs and Pivots or How to turn rows into columns Part 2
Post #629741
Posted Monday, January 5, 2009 6:39 AM

Old Hand

Old HandOld HandOld HandOld HandOld HandOld HandOld HandOld Hand

Group: General Forum Members
Last Login: Friday, November 13, 2015 3:40 AM
Points: 389, Visits: 1,065
Good editorial Steve. Happy New Year!

I agree there's no substitute for a skilled human. I disagree about poor documentation being better than none. It's the bad-beer-and-pizza rule for me: It may be bad beer, but at least it's beer with pizza.

:{> Andy

Andy Leonard
CSO, Linchpin People
Follow me on Twitter: @AndyLeonard
Post #629744
Posted Monday, January 5, 2009 6:40 AM

Old Hand

Old HandOld HandOld HandOld HandOld HandOld HandOld HandOld Hand

Group: General Forum Members
Last Login: Monday, December 2, 2013 1:16 PM
Points: 367, Visits: 303
I work for the US Government and have for 15 or my 20 years programming. When I was first starting I hated documenting anything other than the inline comments I placed in code. I've been fortunate to work on large projects where there was staff to handle the "formal" or System and User documentation, but still we had to provide the basics to the documenters.

After many years of both being at the beginning and ending of projects and in the postion of assuming the work of other developers I have learned the value of documentation. Even on small projects I maintain Code and System (still not real big on producing user documentation) documentation to the level I would like to have if I suddenly had to pick up the project with no overlap of personnel (it does happen on small and medium projects). The documentation must be written to the level of a Junior programmer (not a novice) but much more detailed than an expert needs. Reviewing the documentation available is as much a part of the Code Review process as is looking at the code itself. If the code is not well documented how do you know the programmer intended for the code to do what it is doing?

On a seconday note: When a system crashes there needs to be documentation that can answer any question needed without a having to "dig" through code. It is espically important to have a very strong Disaster Recovery Plan the can return a system to operational status quickly at a new site on new equipment. I'm always amazed everytime I run our DRP to find how many little "gotcha's" there are in getting a system back up and running at a new location. But at least I know if I have to, I can, and most likely any "recovery" required will be much less in scope than we practice for and I'm confident of success.
Post #629747
Posted Monday, January 5, 2009 6:54 AM
SSC Eights!

SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!SSC Eights!

Group: General Forum Members
Last Login: Monday, November 23, 2015 1:10 PM
Points: 812, Visits: 2,111
I write comments before I write code.

Before starting an SP, function, or complex query, I write out in plain English what it will do, what it requrires and what it will return. I find this helps me keep a clear picture in mind as I follow up with the code.


-- FORTRAN manual for Xerox Computers --
Post #629760
Posted Monday, January 5, 2009 7:16 AM


Group: General Forum Members
Last Login: Tuesday, October 29, 2013 5:29 AM
Points: 104, Visits: 721
I'll admit I rarely write comments. About the only time I do is if the code has "gotchas": basically it does things in a way you wouldn't normally expect but actually has to be that way. The rest of the time I rely on properly named classes, methods, and variables. In a sense the code is self-documenting. I often use names that are longer than necessary but really relate what a variable's intended function is, I'll even spend a good bit of time naming and renaming a class or method until I hit upon a name that encapsulates its function. And when I'm writing C# object-oriented code I take the time as well to organize my classes such that using them is a bit self-documenting.

I know proper documentation is nice but I've found so far this to be a nice balance between writing code and maintaining up-to-date documentation.
Post #629777
Posted Monday, January 5, 2009 7:46 AM
Valued Member

Valued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued Member

Group: General Forum Members
Last Login: Friday, October 2, 2009 6:43 AM
Points: 57, Visits: 151
Thirty years ago learning my very first programming language, I also hated documenting programs.

Now, n+ languages later, and 30 years wiser, I document the hell out of anything but the simplest code.

Sometimes I even document that. Especially when learning a new language or function. (Documenting someone elses code seems to really help my learning curve...)

I also try to keep the documentation "reading level" somewhere around the 6th to 8th grade.


Because at 3:00am, after you've been burning your brain since 7:00am the previous morning, your brain no longer operates at the experience level you had when wrote the code.

Just as importantly, if you've been dealing with one issue, and suddenly get hit with another one, you can switch gears a whole lot quicker if you're dealing with code that is well documented in a manner that doesn't require a lot of extra brainpower to decipher.

And, if the junior programmer can understand the code, maybe, just maybe, I won't have to be up at 3:00 am trying to figure out what he did to break mine...

Just my NSHO...

Thanks, Bobw
Post #629801
« Prev Topic | Next Topic »

Add to briefcase 12345»»»

Permissions Expand / Collapse