January 5, 2009 at 8:39 am
I have to say that I am 100% for documentation, and feel that it is as important, if not more so, than the actual code. In this day and age, people just don't stay at one place for 30 years until their own systems are archived. Not documenting code is just plain reckless business practice.
With Dot NET, the comments are stripped out of the compiled version, so it doesn't put a hit on size or performance. This is also true with some other languages.
Lately, I have even become a fan of localized WIKI sites. I have worked a couple places that have had them, and they have proven immensely useful. It does not supplant in-line or header code notes, but for general overall systems, corporate definitions, and even company structure, it is a valuable addition.
I document everything I can. The saying goes, "80% planning, 20% Execution." Another saying goes, "Those who fail to plan, plan to fail."
Yes, it is true that you must have the invaluable personnel resource on hand, as skilled as money can permit. But the gospel of company BI must be actively planned for, written, and maintained; otherwise you may find yourself re-inventing the wheel or duplicating effort. It takes a lot of effort to mentally translate code page after code page, when more often than not, all one is trying to do is digest what the procedure does.
Code will come and go. Even perfect code goes away sometime. The BI of a company, however, is one of the core assets it has.
Personally, I first ask a company what it wants to do, long before I ask what it is doing. That model gets "WIKIfied", along with the core components. From there you have marching and/or maintenance orders, which should be documented in every step. From there I fit in what they currently have, and document as much as I can.
This does many things, not the least of which is it puts you first and foremost among the ones who understand the business.
January 5, 2009 at 8:50 am
bob.willsie (1/5/2009)
Thirty Now, n+ languages later, and 30 years wiser, I document the hell out of anything but the simplest code.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.
100% on the money. I've never once revisited my own (or anyone elses) code and thought there were "to many" comments. It is usually just the opposit. And even with my own code and good comments I've found myself wondering "What the heck was I thinking .... 😀
I require every module to have comments at the top indicating what it's supposed to accomplish (why it exists) and each procedure/function has header comments describing what it is intened to do (references the Functional Requirements Document, when appropriate) and has a section to document all modification (who, what, when and why and references the PR# or ER#). Then the rule of thumb is there should be a comment on what is being accomplished (at a minimum) for every 10 lines of code.
James.
January 5, 2009 at 9:01 am
There really is no self-documenting code. Looking at the code only tells you what it actually does, not what it was meant to do. At the very least, the comments should explain what the code does.
Personally, I rarely write any code but stored procedures. We have a standard for stored procedures that requires a header containing comments that document the purpose, who wrote it, when it was written, and how the procedure parameters are used. We also require that a comment be added every time a change is made that explains what was changed, who changed it, and when it was changed. When a developer submits a new or changed procedure for production, we verify that all required comments are present. Of course, additional comments throughout the code are very helpful to explain particular parts, and to point out changes.
My experience is that comments save a lot of work in the long run and not just for someone new. Someone came to me once about a problem with a report that had been written several years ago. When I asked him why he was asking me about it, he said that according to the comments, I was the author. I looked at the code and had absolutely no recollection of writing it, and was happy that I had written enough comments to explain what it was doing.
January 5, 2009 at 9:13 am
I'm definitely a fan of documentation, both within and outside of the code. As roger.plowman and tiexiem both mentioned, having the "why" of a code module is critical to understanding the intention of the code. It's the part I miss the most when I have to review code (mine or other developers) to try and trouble-shoot some esoteric problem. And it's the part that you just can't get using naming conventions for variables and classes - those only give you the "what".
I had a conversation about documentation with a co-worker within the last year, and she noted that while she thought documentation was very useful, she didn't do it much because she was uncomfortable with it - she thought she didn't write well enough, and was embaressed that someone might read it and critique it. I wonder how many other programmers have that feeling, and how much it interferes with their "desire" to document.
My view is that when I'm trouble-shooting a problem, or going into code to perform an upgrade, it's not the English (my language; feel free to insert your own here) that concerns me, it's the content. I'm not grading anyone on how well they write, I'm just trying to apply business logic to meet the needs of the company I work for. And if the comments help me do that more efficiently, then I'm going to LOVE them! And I don't care if they're written to 5th or 6th grade level, or in broken English, I can read all that just fine - so long as they contain useful information.
And I'm in awe of you who take 6 months to forget code and need the comments; for me it's about 3 months any more! 😛
Steph Brown
January 5, 2009 at 9:16 am
These are great comments on commenting code (recursive comment there?), and I don't avoid documentation, but I don't think it has to be incredibly detailed. Part of my reasoning is that it's not the best use of time. At least not at senior bill rates. Mentoring or helping to pass knowledge along is a better use of someone's time and then let the juniors write additional comments.
code is one thing, but system documentation is something else. There often isn't a good central place to store it, and it becomes hard to both maintain and keep current as things change. It's the evolution of systems not the creation, that makes documentation difficult.
How often have you changed something in a running system and neglected to make a note. Or updated something on the system, but not the DR plan?
I'm sorry, outside of code, it's a great idea, but incredibly difficult to make work on a regular basis with any team larger than 1. So if it's halfway, then what do you do? Do you spend a lot of time on it part of the time and not worry about the others? Do some systems and not others? My thoughts are that if it's not done well all the time, it's going to be broken and so you learn to work with what's broken. Or you build self documenting systems, which is hard to do outside SQL Server. Bare metal restores often have issues because hardware changes in a DR situation. VMs definitely help here, but you can still have issues getting things back up and running and you will likely have sparse documentation.
January 5, 2009 at 9:20 am
Well said, BobW! You have concisely expressed my 25 years in this business.
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 9:29 am
Jack Corbett (1/5/2009)
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.
Nah, it's fine to nitpick. 🙂 I'm always trying to find better ways to program and documenting is a part of that.
I used to document a lot more than I do now but over the years I've discovered the documentation ended up getting out of sync with the code as new features got added, things changed, etc but the documentation didn't get updated. So I stopped putting so much effort in documenting everything and focused on making the code more readable, and that still does include documentation just not as much as I used to do.
I program mostly in C# and not T-SQL and I have noticed a difference in documentation demands. I always feel like I need more documentation for the SQL code than for the C# code. When I used to program in assembly language I documented every line of code. I've noticed different languages can be more expressive of intent than others so the code ends up being more immediately readable and understandable. Of course you have to use the features available to you, for instance in C# using enumerations instead of magic values, using overloaded operators and methods to better indicate what you're trying to accomplish, etc.
I may not document every single line of code but I may document a block of code to explain in general what it's trying to do. If I'm writing a public interface meant to be consumed by other people I'll definitely document it, i.e. a DLL. Writing public documentation to explain how to use a program I have no problem with. For me it's just come down to a balance between coding and documenting. I know it may sound presumptuous of me but I really can look at my code months or years later and understand what's going on because in a sense I've "baked" the documentation into the code.
January 5, 2009 at 9:33 am
A 10 page "Architecture" document hilighting key architectual decisions shouldn't be too hard to create. Heck, this can even be a PowerPoint slide and kept with your source code. That, plus a Word doc that contains common support steps (call it an FAQ if you will), and you're most of the way there. A great measure of these would be the Requirements document you used to develop your solution. Neither document has to be much better than the requirements you used to design it.
Take these two documents in hand, and add in a well managed bug-tracking or support ticketing system, and you are already far better off than many projects I've stumbled acrossed. A great example of this is a project I've come acrossed, where due to a lack of documentation driven by the most sincere and understandable reasons, the IT staff cannot re-create a copy of the same solution in a Test environment. I've been tasked with working on replacing it with updated tools, but all I have is the code in Production to work from. Given that this drives very key financial decisions in the company, I'm not entirely excited about this task...
January 5, 2009 at 10:13 am
Timothy (1/5/2009)
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.
It's great that you do make the comments you do but something to keep in mind and this applies to all who generate new code be it something in .Net or even just T-SQL for an SP or UDF, the problem with only writing comments about what you don't think is easily understood is that not everyone see's everything the same way and so what is a natural assumption for you may not be for all. Assumption is the mother of all Mess-Ups.
Kindest Regards,
Just say No to Facebook!January 5, 2009 at 10:17 am
Somone may have alrady mentioned this as I have not reaed thru all 3 pages of comments (not enough time this morning) but I feel its important to add a point about the documentation.
1 - Don't just document how something works but also note why something works the way it does. For example if you had to impement some method or process that is out of the ordinary/norm (within what is defined as the norm for your organizations best practices & guidelines), explain why you did this so if your code is later reviewed by aomeone else they don't undo what you did because they think you did it wrong instead of doing it diofferent because of 'X'.
2 - Documentation Does Not Have to Be Verbose. I'm guilty of this myself. I have always felt too much info is better then too little but unfortunately unless everyone who will review your code is as excited about reading as you, you have to avoid being verbose in your comments else no one will read them.
Kindest Regards,
Just say No to Facebook!January 5, 2009 at 10:24 am
Good thread, I've picked up some things that I think will help me do a better job documenting my code.
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 10:58 am
I am a fan of Innovasys DocumentX, although Red-Get SQL Documentor or APEX SQL Doc will do just as well.
What's hard about adding a summary, remarks, returns, parameter details and the occassional See also to a stored proc/function?
We use the DocumentX command line utility to rebuild active project database documentation on a nightly basis and other databases on a weekly basis.
The whole lot is on a company intranet. Attach a search engine to it and you have a well cross referenced schema documentation.
Add fields to a table? Spend point sod-all time adding the appropriate MS_DESCRIPTION property. Ditto the table.
If you get a support call at 03:00 on New Years eve then self-documenting code just doesn't cut it.
For non TSQL code there is always a flavour of NDOC.
Documentation does not have to be "war and peace", just enough to let a decaffeinated support person have a slightly less crap New Year.
January 5, 2009 at 11:04 am
I think Steve nailed it when he focused on the prospective audience for documentation. When a team of professional writers (who didn't build the software and/or use it daily for non-trivial work) is hired to "document" a piece of software, there's a problem. Oops. Did I say that out loud?
Just like writing unit tests, developers seem to hate writing comments or documentation, probably because it's nitpicked more than their code. That's a sure sign that there aren't enough code reviews going on... but coders seem to think that The Code™ is for the compiler, not for other programmers (or themselves six months from now). Maybe because somebody told them the compiler ignores comments? The Code™ (including comments) is for other humans!
January 5, 2009 at 11:23 am
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.
David Poole, nice suggestions there.
January 5, 2009 at 11:38 am
I like to do four levels of documentation.
The first is a set of coding standards, for things like variable names, table names, etc. That makes it easier to understand all the code (when adhered to, anyway). 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.
Second is write the code itself so it's easy to read. Layout is important, including breaking up the layout where the codes logically separates. Consistency is critical.
Third, comments in the code. I can sight-read well-layed-out SQL statements, and don't need comments to tell me what they do, but why they do it is critical to comment. No point in a comment that says "this inserts data into a table from another table", on top of an "insert ... select ... " statement. Lots of value to "aggregate data to be used later in the calling proc" as a comment.
Fourth, documentation of the purpose of the code. I haven't found value to documenting the code separately from the code, in terms of a Word document (or whatever) that says, "this proc does X and is used by Y form". The code gets changed, and the documentation gets out of synch. I have found value to "this database is for X application and supplemental reports", or "tables that begin with 'Agents' are about sales agents, including tables 'dbo.Agents', 'dbo.AgentsAddresses', etc."
A user manual is related to this, but that's a whole subject by itself, including help files, form and report design, etc. I find the above very helpful in code documentation.
As for documenting to the level of total beginner, I'd rather let such rely on BoL, SSC, books, etc., since those are going to be more complete, and probably more clear, than anything I could write in a code comment. Yeah, maybe that makes it rougher on a beginner, but I like to assume that people are intelligent and capable and can learn if given the right resources, while, at the same time, assuming that anything worth doing, is worth the effort it takes to learn to do it well.
- 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
Viewing 15 posts - 16 through 30 (of 89 total)
You must be logged in to reply to this topic. Login to reply