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!

‘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!

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.

:)

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.

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.

So that’s where I picked that up. I should re-read that. It’s been a few years.

>>>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