FOR all you programming experts out there

[Kan D.]

please respond to this only if you consider yourself to be an expert in
vba--

QUESTION

What is the best way to document/comment, as you are coding the modules?

The reason I ask:
I have trouble understanding the overall main vision of the entire
program/database, until after I have created the creature. Then I
understand it and can go back to each sub and document/comment within the
sub, what the sub is doing.

I want to be able to do this activity DURING my initial coding.

Does anyone else find this to be a challenge

Thanks for your advice.

Kan

 

[Guest]

While I usually block comments before/after specific routines in a module, I
have set comments to the side on a line by line basis during a routine so I
have an idea of what each line is doing.

Example:

code 'comment
code 'comment
code 'comment

etc.

I will be very interested in others' responses as well. Excellent question!

 

[Tony Toews]

please respond to this only if you consider yourself to be an expert in
vba--

QUESTION

What is the best way to document/comment, as you are coding the modules?

The reason I ask:
I have trouble understanding the overall main vision of the entire
program/database, until after I have created the creature. Then I
understand it and can go back to each sub and document/comment within the
sub, what the sub is doing.

I want to be able to do this activity DURING my initial coding.

I use long, long function and subroutine names. Well, anywhere from
10 to 30 or 40 characters, in camel case, which describe that the
routine does. For example:

Public Function JobSpecificLabourCostRates(JobID As Long) As Boolean

No real comments needed within the code. Now I frequently will put a
one liner at the top of a routine or every 30 or 50 lines of code.

Tony
--
Tony Toews, Microsoft Access MVP
Please respond only in the newsgroups so that others can
read the entire thread of messages.
Microsoft Access Links, Hints, Tips & Accounting Systems at
http://www.granite.ab.ca/accsmstr.htm

 

[Guest]

Kan:

I think you need to distinguish between initial comments which describe the
procedure or function's purpose and explain its arguments, and lines within
the code which describe what the code is doing. Inexperienced developers
often overdo the latter commenting almost every line; its better to restrict
this to explaining the functionality of blocks of code. Here's an example of
the former:

Public Function WordMergeAndSave(strQuery As String, _
strDataDoc As String, _
strMergeFile As String, _
strSaveAs As String, _
Optional blnSuppressBlankLines As Boolean = True)

' Merges data from query into Word document and saves document.
' Accepts: Name of Access query providing data for merge - String.
' Path to Word data file created from query - String.
' Path to Word document to be used for merge - String.
' Path to file as which merged document to be saved - String
' Optional setting to suppress or show blank lines
' if data missing ( Default = True ) – Boolean

Some developers will add their name, the date when the code was originally
written and the dates/descriptions of any revisions.

Here's an example, perhaps not really necessary as the code is pretty self
expnatory, of the latter from the same function:

' check if file already exists
' and get user conformation to
' overwrite if it does.
If Dir(strSaveAs) <> "" Then
strMessage = "MS Word File " & strSaveAs & _
" already exists. Do you wish to overwrite it?"
If MsgBox(strMessage, vbQuestion + vbYesNo, "Mail Merge") = vbNo Then
GoTo Exit_here
End If
End If

I don't see any real problem in commenting code like this as its written.
Difficulties of the kind you describe would suggest to me that the overall
design of the application is perhaps not being given as much thought in the
initial design stages as might be appropriate. I would never start creating
an application until I had firstly mapped out the logical model on paper and
thoroughly tested it by ensuring that it handles not only what might be
expected of it in terms of normal scenarios but also in terms of what might
not be expected but is theoretically possible; and secondly produced, again
on paper, an outline of the user interface design, including whatever
functionality in this for which code (other than standard routines) will be
required.

Ken Sheridan
Stafford, England

 

[Smartin]

please respond to this only if you consider yourself to be an expert in
vba--

QUESTION

What is the best way to document/comment, as you are coding the modules?

The reason I ask:
I have trouble understanding the overall main vision of the entire
program/database, until after I have created the creature. Then I
understand it and can go back to each sub and document/comment within the
sub, what the sub is doing.

I want to be able to do this activity DURING my initial coding.

Does anyone else find this to be a challenge

Thanks for your advice.

Kan

There's a lot of personal preference involved I suppose. One thing I
have been doing lately is document the steps to get something done
before I have written the code. In this way, I can visualize the final
outcome and general path first, and write it down before I get to coding
and forget where I was going. E.g.,

' Set up environment
' Obtain user input
' Loop:
' Parse each table
' Write new values
' Close up

Each step then becomes one or more separate Subs or Functions. I will
usually document each Sub/Function with 1-3 lines explaining its purpose:

Private Sub MakeSessionID()
' Creates a (practically) unique string composed of
' MachineName
' Current time in decimal format with no decimal
' Random number between 0 and 9999
' ... with "." separating each element

If I have written a module or class that I expect to reuse in other
projects I will almost always explain it in detail in the header,
including overall purpose, inputs, outputs, and change log.

 

[Larry Daugherty]

By irritating the majority of people who could give you meaningful
responses by requiring that they be self-proclaimed or certified
"experts" you assure that you won't get many responses. It is
generally accepted that doing a good job of describing and posting
your issue will be the best way to get qualified responses.

I've been called an expert many times over the years. Note that it's
other people's opinion, not mine. I know that I don't know all there
is to know about anything.

Software Engineering is similar to any other kind of engineering: the
desired outcome must be known before the building begins.

You should have a clear understanding of what you intend to build
before you even approach the computer. I'll list some of the steps I
use. Note that the degree of rigor applied varies with the
anticipated user base for the application.

Problem Statement: this is a statement of the problem that I am
addressing or going to solve. It can include both specific and
general issues.

Product Specification: This is a description of the solution I'm
building that will resolve each issue raised in the Problem Statement.

The two items above are always completed before I begin any "code".
If the current project is for a client, I run the above two items by
all interested parties and get them to sign-on to their accuracy and
completeness.

Functional Specification: If you are comfortable with your
capabilities in using the proposed tools (Access in this case) you
might also complete the functional spec before touching the computer.
The Functional Specification contains the descriptions of the
functions that will be used to achieve the solutions

When you are satisfied with the above three elements you have a map of
your application. It is very common that while addressing issues in
the later parts of the project you find it necessary to go back to
earlier parts to make changes. The more you use the same tools in the
same process the less that happens.

At this point I try to imagine the users going through their jobs
using the tool and try to identify and isolate the entities in the
application. When I'm satisfied that I have all that I can imagine I
design the tables, naming each table for the singular of the entity
type. The table wizard gives you ample space for field descriptions.
You'll do well to use it.

Next come the forms with their queries. Because you've done your
homework above, you'll have no doubts about where you are in the
process.

Duane Hookom made a nifty tool, Code Stuffer, available several years
ago. That tool writes a skeleton in a procedure that will put in your
name, the current date and an error handler. It works for both subs
and functions.

Using the steps above you should be able to describe what you're doing
in an Event handler sub or in a given function. Describe just what
this particular piece of code is intended to do. Don't describe the
part(s) of the application that call the procedure. If your current
procedure calls another procedure, put in a line of comment above the
call that describes what you're doing.

That's about as far as your question went ...

HTH

 

[Immanuel Sibero]

I find my self doing more and more of what Tony is describing :
- longer and longer description of the module (whether it's subroutine or
function)
- less and less comments within the module

I'm using longer description of modules because I'm finding myself write
more specific, more atomic, more generic modules. The more specific a module
becomes, the longer the description needs to be. For example, what used to
take me one subroutine (i.e. as a beginner) may now be broken down into six
subroutine/functions in two levels of hierarchy (i.e. call stack).

I'm using less comments within a module because the more specific a module
gets, the more obvious it is to see what the module is doing just by looking
at the module description and the code.

As a side benefit the the above process, the modules become more generic and
therefore reusable. The less a module does the more it becomes reusable and
the more efficient the application becomes. I guess this is what's referred
to as *modular* programming.

In theory, even the most complicated application in Access can be written in
one gigantic subroutine (Ha!), but no one would attempt it since one would
practically have to tell a story to document it. You would find that by
*modularizing* the gigantic subroutine not only make the application more
efficient, it also reduces the need for documentation.

I put comments in my modules here and there, but my general rule is if I
were to strip all my comments I would still have an idea of what a module
does just by looking at the name of the module and the code even after a
week of not looking at it. Otherwise, I would seriously consider breaking
that module down further into smaller modules (i.e. modularizing it).

Modular programming is definitely an art that doesnt have much coverage in
the Access world even though it is very relevant when VBA is involved.
Conceptually, I see a parallel between *modularizing* your VBA programs and
*normalizing* your tables of data. They're both an art, but data normalizati
on receives more coverage because of its huge impact on performance.


Immanuel Sibero

 

[Lancer]

Here's what I do:

function MyFunction()

'purpose - this is where I put the purpose of the funciton
'input - define and explain the params
'process - what this code does, step by step
'output - return value or updated table(s)
'error - how do I error trap: no trap, msgbox, or log entry

'special comments in code where needed.

exit function
end function

 

[aaron.kempf]

comments are a waste of friggin time.

use a good naming convention and you shouldnt need comments

 

[J. Goddard]

I tend to do a lot of comments in line, as I write the code. It doesn't
have to be much, just a line or two explaining what the next block of
code does, e.g.

'
' Check for entries in the table that are missing the end date
'

I find that if I don't comment as I go, I find myself asking "Why the
heck did I do that?" all too often.

You also need to consider the possibility that someone else may need to
read and understand the code at some point.

I recall an instructor in my dim, distant past saying that a reasonably
complex program or procedure should be 25% comments. I have written
FORTRAN programs that are higher than that.

John

 

[Duane Hookom]

I use MZ-Tools to add error handling and comment headers to most of my code.
I will often explain the use of function and procedure arguments directly
following the Function/Sub line.

I will also write comments prior to writing code. If you don't know why you
are going to write your code then don't write any code. So commenting of the
next section of code comes easy. Also, I get interrupted a lot and comments
help me get my old brain focused back on what I was hoping to do with the
code. This is kinda my way of "thinking out loud".

 

[Kan D.]

Thank you, everyone!

I use MZ-Tools to add error handling and comment headers to most of my
code. I will often explain the use of function and procedure arguments
directly following the Function/Sub line.

I will also write comments prior to writing code. If you don't know why
you are going to write your code then don't write any code. So commenting
of the next section of code comes easy. Also, I get interrupted a lot and
comments help me get my old brain focused back on what I was hoping to do
with the code. This is kinda my way of "thinking out loud".

 

[Guest]

Ken,
I'm looking for code about merge, in your example, I see wyou wrote a
function about merge.
Let me tell what I need.
I frequently use automation to ms excel and I don't have problem.
But I have a talbe, where a field is memo and then if I export to excel
doesn't work, it export I think 255 caracthers.
So, I need export queries based in this table.
I tried with docmd.outputto but the format is not good. The columns width is
not properly and I want landscape format.
So, I would like create a template with the logo and formating the page,
margins etc and then export to it.
Could you Help me?

Thanks Lot
JP