January 4, 2009 at 10:02 pm
Comments posted to this topic are about the item A Dearth of Comments
January 5, 2009 at 2:02 am
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.
January 5, 2009 at 3:04 am
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.
January 5, 2009 at 5:18 am
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
Arthur Fuller
cell: 647-710-1314
Only two businesses refer to their clients as users: drug-dealing and software development.
-- Arthur Fuller
January 5, 2009 at 6:34 am
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
Consultant - Straight Path Solutions
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
January 5, 2009 at 6:39 am
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, Chief Data Engineer, Enterprise Data & Analytics
January 5, 2009 at 6:40 am
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.
January 5, 2009 at 6:54 am
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 --
January 5, 2009 at 7:16 am
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.
January 5, 2009 at 7:46 am
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.
Why?
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
January 5, 2009 at 7:47 am
I created and maintain what amounts to the corporate database backbone system we used for everything from dispatch to accounting to management and data entry.
It's about 100,000 lines of code and over 125 tables, with at least that many queries and whatnot.
By weight I'd say comments make up about 40% of the line count. In addition I've created over 20 development documents detailing various subsystems, along with overview documentation--and that doesn't count the documents intended for third parties (customers) who want to create files the system can use as input.
The documentation is written at a Junior-to-novice level because there's no such thing as a universal expert--everybody's novice at *something* and I want to make sure the system is maintainable should I get hit by the proverbial bus. I spend a lot of comments on the "why" as opposed to the "how".
Nor does this count user side documentation, including a 100+ page manual (written at the 5'th grade level) and an online help system that automatically displays field level help on every field in the system, and screen level help as well.
Not to mention an intraweb site containing task-oriented tutorials. 🙂
Documentation is your friend. The time and effort needed to keep it accurate upfront will be repaid a thousand-fold the first time someone who isn't you looks at the code / system / database.
January 5, 2009 at 8:17 am
As a consultant, it is my job to document my work. More often than not, those that will support what I've done will be below my skill level (which, really, is why they hired consultants to build the project in the first place). It is the job of each code-level technician to write inline code documentation, but it is also the job of the Architect and Project Manager to provide standards and templates for user and system documentation. Why was a specific architectual path taken? What are some basic procedures for support? The common answers of "its a best practice" or "I shouldn't have to tell you how to do your job" don't cut it here. I see many that are willing to claim that they fill the roles of Architect or Project Manger, but very seldom to I see those that are willing to put in the non-coding legwork.
How many of us have built something and left only to come back to see it completely bastardised? Before we start blaming all the morons for ruining our work, we need to stop and think about what kinds of documentation we left with our work.
January 5, 2009 at 8:24 am
Timothy (1/5/2009)
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.
Not to nitpick, but in my experience, this really doesn't work well. I've worked with programmers who believe this works well, and it does for them while they are on that project, but for others reading their code and when they go back 6 months later, it has fallen short. I thought this way when I first started programming, but have learned it is better to be verbose with comments than think my code is self-documenting. As I said in my first post, I don't comment enough, nor clearly enough when I do.
Jack Corbett
Consultant - Straight Path Solutions
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
January 5, 2009 at 8:27 am
Michael Ross (1/5/2009)
How many of us have built something and left only to come back to see it completely bastardised? Before we start blaming all the morons for ruining our work, we need to stop and think about what kinds of documentation we left with our work.
Exactly.
I agree with the rest of your post as well, but this summation is so true.
Jack Corbett
Consultant - Straight Path Solutions
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
January 5, 2009 at 8:33 am
I like this topic - it hits a hotspot with me.
I too hate to write the 'reinvent the wheel'-level documentation for code I've written myself, but when I read documentation for APIs or some other packaged software I'm using, I expect every detail and aspect to be documented meticulously. Kind of self-centered, huh?
When writing comments in code I've written, I do it mainly as a reminder to myself about what I was thinking and why I did things a certain way. I've been told by other programmers coming behind me that my comments really helped them.
Cheers!
MitchellT
Viewing 15 posts - 1 through 15 (of 89 total)
You must be logged in to reply to this topic. Login to reply