Time for something contentious.
I’m going to combine documentation and commenting code, hopefully you’ll see why. Here I am talking about Exel/VBA based business tools only. This will almost certainly not apply if you are using a different technology to solve a different issue.
Heres a question – do you like documenting your work? If so why?, If not why not?
Do you think you are a conscientious developer?
Me – no I don’t like it, because I think its generally pointless. Much bigger benefits can be had by focusing on other areas in my experience. And yes I think I am conscientious, thats why I don’t like wasting clients money on low value work like keeping unused documentation up to date.
Beginners don’t comment/document because they don’t realise they need to.
Intermediates do comment and document (a bit) because they recognise they need to.
Advanced developers neither comment nor document because they dont need to.
Beginner/Intermediate developers (and we all go through this whenever we work on an unfamiliar project, or with an unfamiliar technology) often develop as a series of challenges and battles, and are just relieved when something finally seems to work. Their work often lacks design clarity and often includes workarounds and compromises due to lack of knowledge and time pressures. Beginners don’t realise someone (possibly them in 2 years time) will have to come back to this work to change it for new business requirements, so dont document/comment.
Intermediates have had their fingers burnt looking after old work – possibly their own possibly someone elses. They provide comments and documentation because the work needs it.
Advanced devs bring all their experience and resources to bear, they are confident they can implement whatever they design. So they focus on a clear design, they consider how all the components of the system will interact to get the job done, they revise and optimise and simplify on paper. When they do finally fire up a computer its to copy and paste proven components from previous projects, and to provide some glue code and project specific stuff. Advanced developers work tirelessly to remove the need to document or comment.
In code, short well named routines that do 1 thing well do not need further comment.
In worksheets well named single purpose sheets with a good name and a clear title should make their purpose clear. in cells short clear functions that only rely on several other cells, and have a clear description in a cell nearby do not need further description.
I think building with the mind set that ‘I’ll leave this monster, and just explain it in the documentation’ whether concious or unconcious is not a high quality approach. Building whilst thinking, ‘this needs to be totally self explanatory, how can I make it more simple to follow?’, in my opinion will lead to a higher quality easier to manage product.
The only documentation that I think is worthwhile is details of the underlying business assumptions that drive the model. Anything that describes technical aspects of the system probably represents a failure, to either design the system well, or to target the documentation properly.
Agree? disagree?
Cheers
Simon
Smurf on Spreadsheets 
Wednesday, 14th February, 2007 at 10:04 pm |
LOL!
We had this discussion last July, so nothing I say here will be new to you, but I will repeat it (because I am a boring old fart, and for the benefit of others).
Documentation is vital IMO, partly because it is needed, partly because the client expects it and is likely to think you are cutting corners if you don’t supply it. Where our thoughts come together probably is in the quality of the documentation. Reams and reams of documents are pointless, it will be unreadable, and unmaintainable. Documents should concentrate on the core issues, and be succinct, more bullet-point like. As Simon says, the core business assumptions should be documented, the core design assumptions, implementation assumptions, all documented in a way that is maintainable.
A little aside, at one of my previous employers there was a system being developed where they presented a business case that was over 4,000 pages long (sic!). They tried to anticipate every question, and reply before being asked. Needless to say, the project was cancelled, but not before they had spent over £20M on it (and no, I didn’t work on it, I built its replacement for £5M).
I also am not as confident in the ability of advanced developers to think as clearly as you are, a good coder is necessarily clear-minded. I agree far too much of comments is useless, I remember I worked with a great programmer once, and an example of her code is
‘close connection
oConn.Close
totally redundant. But, your commenting strategy seems to be predicated upon this premise … short well named routines that do 1 thing well do not need further comment … I agree that such routines, when looked at in isolation could and should be easy to understand (although there are circumstances even here where it might just not be possible to self-documenting), but these things do not work in isolation, they are invariably part of a much bigger application, and it is being able to piece that jigsaw together that is the big problem. That is where the real difficulty lies, not in the individual procedures, but the big picture. My view is that this is best addressed with a good, succinct, focused design doc, and a few lower-level comments around major coding structures.
In principle, I think I agree with you, it is just the degree.
Wednesday, 14th February, 2007 at 10:24 pm |
Writing comments is the first thing I do. I write out what I want to do in English, then go back and put the VBA underneath the comments. It helps me work out some of the logic in my head before I start coding. I assume you, and everyone else, does some sort of planning before you write a procedure. You may do it in your head or with pencil and paper. I do it with comments.
Thursday, 15th February, 2007 at 10:23 am |
Bob
Its not going to be much of an argument if we broadly agree!
Dick, thats a good approach, as recommended by Steve Mcconnell in my favourite SW book. http://www.cc2e.com/Default.aspx
Yeah I do my planning on paper, I pretty much have my routines written out before I fire up the editor.
One issue with comments is they dont get updated when the code does, I’ve learnt now to totally ignore comments, I only read the code. A module header can be nice explaining the business purpose, but in routines, I just ignore all the green stuff.
cheers
Simon
Thursday, 15th February, 2007 at 10:47 am |
My experience with documentation, and I talking more user help here, is that the end users just don’t use it. For a company application which I support, as well as write, most questions can be answered by referring the user to the help file. But they just don’t bother to look.
And we see this so many times when helping users in the NGs and forums.
As for comments I have 3 types of commenting.
• Overall explanation and revision history, which is placed at the top of a code module.
• Quick explanation at the beginning of a routine. I do not to down to the detail of explaining incoming arguments but will mention any that are used to return values.
• In line comments. These are used to explain something tricky or new and act as self reminders when returning to code. (Upon checking some of my code it appears I am guilty of the obvious comment syndrome.)
Comments and documentation are only of use if they are up to date. If you can not bring yourself to maintain your comments as well as your code don’t bother with them.
Thursday, 15th February, 2007 at 1:39 pm |
Simon,
>>>Heres a question – do you like documenting your work? If so why?
I get full paid to document in plain English for my large customers so money talks and I walk.
Kind regards,
Dennis
Thursday, 15th February, 2007 at 2:31 pm |
“as recommended by Steve Mcconnell”
So that’s where I picked that up. I should re-read that. It’s been a few years.
Thursday, 15th February, 2007 at 2:55 pm |
Dick
Its on the shelf above your laptop:
http://www.dailydoseofexcel.com/archives/2006/12/10/new-desk/
Thursday, 15th February, 2007 at 4:25 pm |
Dennis
Good point, well made.
Thursday, 15th February, 2007 at 8:29 pm |
I’m also of the “comment first, code second” variety, although I haven’t read Code Complete. I just decided one day that if I was going to write it out, it might as well be in the VBE.
When I was starting, I commented everything, but comment less now. I try to keep my comments purposeful, though… what each branch of an If statement is trying to accomplish for example. (Not so much if it’s a one liner, but definately if it’s more than 10.)
I try not to comment to the extent that Bob showed above any more, though. ;)
Personally, I’d rather over comment than undercomment my code, and I do make an effort to keep them updated. Nothing bugs me more than picking up someone else’s project and having to figure out what they wrote because they couldn’t even bother with a high level overview.
Friday, 16th February, 2007 at 11:19 am |
Interesting:
Firstly, I’m basically very lazy, I tend not to think of other people having to work with my code (poor practice I know!) I under comment (maybe not in Simons book). When I do comment it tends to be for blocks of code, so I guess it’s different to what Dick and Ken do because I think/plan as I go along. I don’t think I could write it out at the top because I change what I want to do as I go along? Like I write some code to do a task, then as I need to use that code again I’ll pull it out in to a function and make it more general etc.
One place where I have started to use comment more is when closing loops, now when I open a loop the next code I write is a comment, then close the loop i.e.
Do Until x = 10
code
‘close x loop
Loop
I find this useful.
As for documentation, when I start to write an app, I open up word and write down in help file like fashion, I will define what each functional part does, then write “dev notes” and “user notes”. I will keep the dev notes for me, removing them for the user/sponsor and also using it for help files. I don’t like writing it, but I do find it useful at a later stage – not so much for the code, but for the BL.
Friday, 16th February, 2007 at 11:24 am |
Oh,
The other thing I’ll say is that i watch some of the videos here:
http://webcast.berkeley.edu/course_details.php?seriesid=1906978270
mainly talks about Lisp, but his POV is that good code does not need comments – its a lovely thought!
Saturday, 17th February, 2007 at 12:09 am |
“I think/plan as I go along”
Interesting, Ross, but doesn’t negate the method for me. I code on the fly too, but within my original plan. I might comment out something like:
‘Prompt user for file
‘ User cancelled, so exit
‘Determine valid data
‘ Apply formula index
‘ Autofilters for items to remove
‘ Delete
‘Reformat Reports
‘ Set page setups
‘Save file
‘Print file
‘Email file
Basically, I work out the logic of what I want to accomplish and comment it, rather than doing it on paper. I then go back and code it. I may find that I missed something, or change the order, but it can still be done on the fly.
:)
Tuesday, 20th February, 2007 at 3:22 pm |
I’m kind of a mix I guess, in that I start off any large projects like Dick, Ken & co, where I plan out the large sections of what I want to do by putting down
‘Step 1 Description
‘Step 2 Description
‘Step 3 Description
etc
I find this approach is useful as a starting place to plan what I want to do – mainly because I can type much more quickly than I can write, and I always lose those pesky bits of paper on which I’ve scribbled my genius idea to interface Excel to the coffee machine…
Though after I’ve got my teeth into it, and amend my plan of action as I’m going, I usually have to go back and change a lot of the comments so that someone else can follow what on earth it’s actually doing (though not necessarily WHY it does it… ;-) ), and dump a lot of the original comments I wrote in the first place because they no longer apply to what’s happening now!
Tuesday, 20th February, 2007 at 4:23 pm |
Andy I’ve noticed that on the NGs too, I don’t spose it would be much use replying RTFM or try google to every post. Your comment approach seems reasonable, I guess the last section covers me -‘if you aren’t going to keep them up to date…’
I use Stephen Bullens call tree which is great for mapping out an overview.
I try to keep my blocks short (if..Then etc) so I do not need a closing comment, I do add these to other peoples overly long blocks though.
Ken I would code each of your comments as a seperate function returning true for success.
MikeC any plans to share that Excel/Coffee machine code? That could be a real winner!