By using this site, you agree to our updated Privacy Policy and our Terms of Use. Manage your Cookies Settings.
464,368 Members | 1,240 Online
Bytes IT Community
+ Ask a Question
Need help? Post your question and get tips & solutions from a community of 464,368 IT Pros & Developers. It's quick & easy.

documenting access apps

P: n/a
Hi,

I am mildly familiar with ms access developement and I have been asked to
port and document a ms access app. I expect the porting (97 to XP) to be
fairly straightforward. However documenting it is another matter. How do you
people document your access apps?
Just create an ERD and have comments in the vba code? List all the forms and
it's purpose ?
Are there any methodologies / best practices / examples I can look at?
thanks in advance

-- jelmer
Nov 12 '05 #1
Share this Question
Share on Google+
17 Replies

P: n/a
Access has a builtin documenter (Tools - Analyze - Documenter) that will
print a fair amount of information about the objects in the db. The Access
Relationship window can also be printed, although sometimes it doesn't print
very well ... however, there are some third-party utilities out there that
supposedly do a better job.

RE: Porting - make sure to set your reference to DAO in the new Access XP
project.

--
Scott McDaniel
CS Computer Software
Visual Basic - Access - Sql Server - ASP

"Smash forehead on keyboard to continue ... "
"Jelmer" <jk******@planet.nl> wrote in message
news:c0**********@reader10.wxs.nl...
Hi,

I am mildly familiar with ms access developement and I have been asked to
port and document a ms access app. I expect the porting (97 to XP) to be
fairly straightforward. However documenting it is another matter. How do you people document your access apps?
Just create an ERD and have comments in the vba code? List all the forms and it's purpose ?
Are there any methodologies / best practices / examples I can look at?
thanks in advance

-- jelmer

Nov 12 '05 #2

P: n/a
NB
I think the Documenter may be good for very simple and small apps. An
average app may generate a few thousand page long document which, in
my opinion, is not very practical to go through.

I'm also interested to know if there is any better 3rd-party tool out
there

NB
Nov 12 '05 #3

P: n/a
Jelmer wrote:
Hi,

I am mildly familiar with ms access developement and I have been asked to
port and document a ms access app. I expect the porting (97 to XP) to be
fairly straightforward. However documenting it is another matter. How do you
people document your access apps?
I feel that is an *extremely* sensitive issue. Some people simply don't.
Others write more comments than actual code lines, but never explain the
SQL for, or the existence of, a single query.

Speaking for myself, I initially did no documentation at all, relying on
my accurate adn strong memory. And that works. For me.
The very first project I did together with someone else, that approach
failed most miserably.

I find Access doesn't really allow for a centralized approach. It is far
too easy to create just another query, or a 'temporary' report to see if
something works. If you need a solid system documentation, you also need
a project manager (that can be you but that takes quite a lot of discipline)

This is all about during-development. When you need to unravel a
complete application afterwards, you must of course dig your way through
functionality. Usually I try to draw the form hierarchy, if any, to get
some hold of the interface; and I carefully study the
tables/relationships layout (no, I do the layout, and study the design).
For the latter, I've invented some tools that produce a complete
table/field list. I certainly suggest you look into the Tools section on
my site, NavQueries will be something for you but also FindCode and
FindName have been life savers for me sometimes.
Just create an ERD and have comments in the vba code? List all the forms and
it's purpose ?
Are there any methodologies / best practices / examples I can look at?
thanks in advance


What you need is not easy to specify in advance. The enormous problem
with the built-in Documenter is that it produces data, not information.
Many details are irrelevant and just clutter the pages. I tried once to
omit all settings that do not deviate from a standard (most frequent, or
my preference, whatever) but I didn't have time to finish that then.

Jelmer? You Dutch?
--
Bas Cost Budde
http://www.heuveltop.org/BasCB
but the domain is nl

Nov 12 '05 #4

P: n/a
NB wrote:
I think the Documenter may be good for very simple and small apps. An
average app may generate a few thousand page long document which, in
my opinion, is not very practical to go through.

I'm also interested to know if there is any better 3rd-party tool out
there


I have seen several documentation systems, both during-design and
reporting-afterwards, but most of them are tremendously overkill for my
information need.

Later, when I'm old and wise, I'd like to interview many developers and
find/formulate/implement a common need system.

Care to share your wishes over email? I don't think this is the forum to
do so.
--
Bas Cost Budde
http://www.heuveltop.org/BasCB
but the domain is nl

Nov 12 '05 #5

P: n/a
On Sun, 8 Feb 2004 16:14:19 +0100, "Jelmer" <jk******@planet.nl> wrote:
Hi,

I am mildly familiar with ms access developement and I have been asked to
port and document a ms access app. I expect the porting (97 to XP) to be
fairly straightforward. However documenting it is another matter. How do you
people document your access apps?
Just create an ERD and have comments in the vba code? List all the forms and
it's purpose ?
Are there any methodologies / best practices / examples I can look at?
thanks in advance

-- jelmer


For most Access projects, the most important thing to document is the ERD.
Unfortunately, the single-view relationships diagram in Access is not very
helpful, though you can search recent posts for some tools written by Micheal
Kaplan and Stephen Lebans that can help with that. Otherwise, the more
expensive versions of Visio have tools for ERDs compatible with Access.

To me, the next most important documentation is the in-project documentation.
The documentation is both more clear in meaning and more likely to be properly
maintained if it is located right with the thing it documents. In fact,
documentation outside the system is usually not maintained, and becomes worse
than useless in no time. Documentation inside the system can be printed using
database documenter tools, and/or you can do things like flagging code
comments with tags, and pipe the code output through FIND or some such thing
to filter out the documentation to print. Of cours, you'll have to add
comments that document how to employ the tags.

So, on the list of in-place documentation...

1. Use the Description properties of Forms, Reports, Queries, etc.
Personally, I also like to preface the descriptions of objects normally used
within other objects with a Dash, and add more dashes for more deeply nested
objects. I also like to use all upper-case for top-level objects (not
sub-nested) to make them easier to pick out in the list. Always leave the
database window in "Details" view when you close the database.
2. In code, document the purposes of things. Try not do document the
functions of things unless a functional detail is important to the things that
will use it. Documentation function rather than purpose/usage will be out of
date soon, and that's worse than no documetation at all. If the code's
function is unclear and not maintainable without explanation, that it
something someone should fix.
3. In Access, it's easy to hide important aspects of a program's function in
popup menus, event properties, etc. You can uses database documenters to see
what all these things are, then back-trace their purposes. It's good to
document such hidden things in hidden labels on the form or in the objects'
code modules.
Nov 12 '05 #6

P: n/a
CDB
Apart from VBA comments describing the function of the next segment of code,
I gave up most internal documentation. My very strong preference and
practice for over a decade is to use a design document.

The fundamentals are the same over that time, but there have been many
refinements added. It is revised and reprinted many times during the
development stage, and used as a worksheet to record what has been created.

The sections are:

Notes. The first statement is always "the purpose of this database is
to...", and everything that is done is measured by this statement. Contact
names are followed by developer tasks.

Environment. Describes access version, SP level, db engine and references.
Also extra files and shortcuts. Monitor resolution.

Application. This is the modules and supporting objects, command bars and
registry keys.

Startup. I run a number of checks to ensure that the environment is solid.
The convoluted code and its required objects are described here.

The next sections describe the main menu bar and its items. Typically, they
are:

File. Usually only Switch Data Files, Page Setup, and Exit.

Reference. This provides access to the basic "look up" tables, starting with
the System record. Access to this menus is usually restricted to trusted
users.

(Task menus). This is the main bulk of the application. The design document
is in landscape format to allow for headings of the new item, object, this
course, subsidiary object, subsidiary source, notes. This allows for a full
structural description of the menu item and the object that it calls, along
with sub forms, reports, buttons, queries and tables, and specialised
modules.

Any person looking at any of my applications canned, armed with this design
document, quickly come to understand what everything is there for.

Tools. This includes sorting, calculator, current users, View Startup log,
Email event log, and tech support page.

Windows. The standard access Windows menu.

Dev menu pop-up. This is called by a keyboard shortcut for which the user
never learns about. It includes the Tools I have made to aid in the
development work.

After the main menu sections, the following are listed:

Tables, Fields, indexes. This is created automatically by a Dev menu item.

Reference Tables Values. Any of these values are a used in code and queries
to filter records, and this quick reference is invaluable.

Relationships. The standard access drawing, and a custom relationships
report which often picks up errors.

UI Specifications. The special properties and colours, etc, for this
application.

Forms and reports. Copies of actual forms and reports.

That is a total of 18 pages for my latest application. The design document
is my "Bible".

Clive
"Steve Jorgensen" <no****@nospam.nospam> wrote in message
news:f2********************************@4ax.com...
On Sun, 8 Feb 2004 16:14:19 +0100, "Jelmer" <jk******@planet.nl> wrote:
Hi,

I am mildly familiar with ms access developement and I have been asked to
port and document a ms access app. I expect the porting (97 to XP) to be
fairly straightforward. However documenting it is another matter. How do youpeople document your access apps?
Just create an ERD and have comments in the vba code? List all the forms andit's purpose ?
Are there any methodologies / best practices / examples I can look at?
thanks in advance

-- jelmer

For most Access projects, the most important thing to document is the ERD.
Unfortunately, the single-view relationships diagram in Access is not very
helpful, though you can search recent posts for some tools written by

Micheal Kaplan and Stephen Lebans that can help with that. Otherwise, the more
expensive versions of Visio have tools for ERDs compatible with Access.

To me, the next most important documentation is the in-project documentation. The documentation is both more clear in meaning and more likely to be properly maintained if it is located right with the thing it documents. In fact,
documentation outside the system is usually not maintained, and becomes worse than useless in no time. Documentation inside the system can be printed using database documenter tools, and/or you can do things like flagging code
comments with tags, and pipe the code output through FIND or some such thing to filter out the documentation to print. Of cours, you'll have to add
comments that document how to employ the tags.

So, on the list of in-place documentation...

1. Use the Description properties of Forms, Reports, Queries, etc.
Personally, I also like to preface the descriptions of objects normally used within other objects with a Dash, and add more dashes for more deeply nested objects. I also like to use all upper-case for top-level objects (not
sub-nested) to make them easier to pick out in the list. Always leave the
database window in "Details" view when you close the database.
2. In code, document the purposes of things. Try not do document the
functions of things unless a functional detail is important to the things that will use it. Documentation function rather than purpose/usage will be out of date soon, and that's worse than no documetation at all. If the code's
function is unclear and not maintainable without explanation, that it
something someone should fix.
3. In Access, it's easy to hide important aspects of a program's function in popup menus, event properties, etc. You can uses database documenters to see what all these things are, then back-trace their purposes. It's good to
document such hidden things in hidden labels on the form or in the objects' code modules.

Nov 12 '05 #7

P: n/a
On Tue, 10 Feb 2004 14:42:57 +1300, "CDB" <al***@delete.wave.co.nz> wrote:
Apart from VBA comments describing the function of the next segment of code,
I gave up most internal documentation. My very strong preference and
practice for over a decade is to use a design document.
Really? I have yet to see a design document that had much to do with the
state of the application by the time I read it. That makes the design
docunment not much use, though it took someone a lot of time to create. I
have had the idea, recently, to at least maintain a requirements document, and
never update code prior to updating the requirements, since the purpose of any
code should be to meet some requirement, or why write it? This also keeps the
requirements in sync with the program and helps keep development on a clear
track.
The fundamentals are the same over that time, but there have been many
refinements added. It is revised and reprinted many times during the
development stage, and used as a worksheet to record what has been created.

The sections are:

Notes. The first statement is always "the purpose of this database is
to...", and everything that is done is measured by this statement. Contact
names are followed by developer tasks.

Environment. Describes access version, SP level, db engine and references.
Also extra files and shortcuts. Monitor resolution.

Application. This is the modules and supporting objects, command bars and
registry keys.

Startup. I run a number of checks to ensure that the environment is solid.
The convoluted code and its required objects are described here.

The next sections describe the main menu bar and its items. Typically, they
are:

File. Usually only Switch Data Files, Page Setup, and Exit.

Reference. This provides access to the basic "look up" tables, starting with
the System record. Access to this menus is usually restricted to trusted
users.

(Task menus). This is the main bulk of the application. The design document
is in landscape format to allow for headings of the new item, object, this
course, subsidiary object, subsidiary source, notes. This allows for a full
structural description of the menu item and the object that it calls, along
with sub forms, reports, buttons, queries and tables, and specialised
modules.

Any person looking at any of my applications canned, armed with this design
document, quickly come to understand what everything is there for.

Tools. This includes sorting, calculator, current users, View Startup log,
Email event log, and tech support page.

Windows. The standard access Windows menu.

Dev menu pop-up. This is called by a keyboard shortcut for which the user
never learns about. It includes the Tools I have made to aid in the
development work.

After the main menu sections, the following are listed:

Tables, Fields, indexes. This is created automatically by a Dev menu item.

Reference Tables Values. Any of these values are a used in code and queries
to filter records, and this quick reference is invaluable.

Relationships. The standard access drawing, and a custom relationships
report which often picks up errors.

UI Specifications. The special properties and colours, etc, for this
application.

Forms and reports. Copies of actual forms and reports.

That is a total of 18 pages for my latest application. The design document
is my "Bible".

Clive


I think all these things are important, but I prefer to try to find ways to
embed them within the application rather than maintaining them separately.
For one thing, they'll be more likely to be maintained because you can't
forget about them - they're right there in the thing you're modifying. For
another thing, you never need to worry about whether external files have been
properly kept track of or whether you're looking at the right version for the
version of the system you're examining.
Nov 12 '05 #8

P: n/a
Steve Jorgensen wrote:
I think all these things are important, but I prefer to try to find ways to
embed them within the application rather than maintaining them separately.
For one thing, they'll be more likely to be maintained because you can't
forget about them - they're right there in the thing you're modifying. For
another thing, you never need to worry about whether external files have been
properly kept track of or whether you're looking at the right version for the
version of the system you're examining.


Probably the general idea for documentation to be successful is when
development follows documentation. General practise is the other way
around, I know, but if a manager in a project can 'enforce'
documentation first (even sketch-like) that will improve the
synchronization.

--
Bas Cost Budde
http://www.heuveltop.org/BasCB
but the domain is nl

Nov 12 '05 #9

P: n/a
On Tue, 10 Feb 2004 08:47:19 +0100, Bas Cost Budde <ba*@heuveltop.org> wrote:
Steve Jorgensen wrote:
I think all these things are important, but I prefer to try to find ways to
embed them within the application rather than maintaining them separately.
For one thing, they'll be more likely to be maintained because you can't
forget about them - they're right there in the thing you're modifying. For
another thing, you never need to worry about whether external files have been
properly kept track of or whether you're looking at the right version for the
version of the system you're examining.


Probably the general idea for documentation to be successful is when
development follows documentation. General practise is the other way
around, I know, but if a manager in a project can 'enforce'
documentation first (even sketch-like) that will improve the
synchronization.


I'm coming to the same conclusion, but I'd also want to add that the whole
spec doesn't have to be done before the program, just that each part or change
should be made to the documentation first, then the code - and i still think
it's better to try to put it -in- the code.
Nov 12 '05 #10

P: n/a
CDB
Steve, my design documents are essentially workbooks. The one for the
current project is usually open in front of me and is continually annotated
as the work progresses, or in advance, as you suggest.

In particular, I value its recording of all the sub forms for a form, the
buttons, pop-up forms, etc. By the time I have a collection of 12 to 20
access objects coming from one menu item, I find it very easy to lose track
of the structure.

By the way, the design document also forms an " implementation of
requirements" document, and is usually the basis for my time and cost
estimates.

No coding detail is included, apart from reference to specialised modules,
for some form or report which is dependent on that module. The design
document describes the forest and its blocks, not the individual coding
trees. Anyone who can't recognise a tree should not be messing around in the
forest.

When in full flight, some pages of the design document may be updated and
reprinted three times in one day, simply because the handwritten notes
become too messy. And I want a clear statement of the building to date, on
which the next floor will be built.

All of my applications are installed remotely. The last handful have been
installed in the USA, from New Zealand. It is essential to have a checklist
of the supporting files etc. My agent or principal receives a copy of
updated design documents to help them with installation and maintenance
questions.

This approach suits my skills and shortcomings, and provides a good basis
when revisiting an application, or when another programmer is assisting or
taking over the application.

Clive

"Steve Jorgensen" <no****@nospam.nospam> wrote in message
news:0h********************************@4ax.com...
On Tue, 10 Feb 2004 14:42:57 +1300, "CDB" <al***@delete.wave.co.nz> wrote:
Apart from VBA comments describing the function of the next segment of code,I gave up most internal documentation. My very strong preference and
practice for over a decade is to use a design document.
Really? I have yet to see a design document that had much to do with the
state of the application by the time I read it. That makes the design
docunment not much use, though it took someone a lot of time to create. I
have had the idea, recently, to at least maintain a requirements document,

and never update code prior to updating the requirements, since the purpose of any code should be to meet some requirement, or why write it? This also keeps the requirements in sync with the program and helps keep development on a clear track. ....
I think all these things are important, but I prefer to try to find ways to embed them within the application rather than maintaining them separately.
For one thing, they'll be more likely to be maintained because you can't
forget about them - they're right there in the thing you're modifying. For another thing, you never need to worry about whether external files have been properly kept track of or whether you're looking at the right version for the version of the system you're examining..

Nov 12 '05 #11

P: n/a
Hi Steve,

Comments inline

Steve Jorgensen <no****@nospam.nospam> wrote in message news:<f2********************************@4ax.com>. ..
On Sun, 8 Feb 2004 16:14:19 +0100, "Jelmer" <jk******@planet.nl> wrote: For most Access projects, the most important thing to document is the ERD.
Agreed. Very important but oft neglected.

As well as the ERD, a data dictionary I find to be invaluable to get
up to speed on an unfamilar system. I'm maintaining a system which has
over 1000 fields, many of them apparently unused, others named in a
manner which has nothing to do with the actual data stored in the
field. Try to figure out the difference between lngTotal_Sheet and
lngTotal_Worked and lngAll_Worked (argh L/R applied to field names) by
looking at the field names.

Naming you tables and fields properly is a good start to 'documenting'
your system.

Filling out the description of the field is even better (and it's easy
to write a tool to extract this).

There is an international standard on entity and attribute naming
conventions (Lyle Fairfield posted a link to it, as Joe Celko I
think). Well worth a read.
To me, the next most important documentation is the in-project documentation.


Code Complete by McConnell has some excellent stuff on in-project
documentation.

He calls it self-documentation if I remember correctly. eg name your
procedures etc meaningfully

It's also got great stuff about the size of projects and the amount of
documentation that is 'required' and the overall purpose of
documentation.

The guy before me where I am developed a great system were all changes
need to go through a 'Systems Change Request' process, and the changes
are added to a database, so all the changes to the system are, to some
degree, at least, documented.

I've inherited systems with thousands of lines of code with a mini
post-it note as the documentation. It's not a good feeling.

Having said all that I still find myself wrestling with the
documentation monster on a regular basis as personally I find
documentation like flossing one's teeth. You know you've should do it
but it's easy to skip.

Visio is an invaluable tool in the wrestling pit IMO.

Reams of documentation of 'this is the print button', 'this is the
next button' etc is IMO a waste of time. It should be bleedin' obvious
to a developer that it's a print button. Equally annoying is

'open report
Docmd.OpenReport "Whatever"

or a 700 line procedure....

Peter
Nov 12 '05 #12

P: n/a
On Wed, 11 Feb 2004 00:15:26 +1300, "CDB" <al***@delete.wave.co.nz> wrote:
Steve, my design documents are essentially workbooks. The one for the
current project is usually open in front of me and is continually annotated
as the work progresses, or in advance, as you suggest.

In particular, I value its recording of all the sub forms for a form, the
buttons, pop-up forms, etc. By the time I have a collection of 12 to 20
access objects coming from one menu item, I find it very easy to lose track
of the structure.
Well, I suppose, I might have been overstating my objection. Based on your
reply, I actually think we pretty much agree. My experience has not been with
documentation done the way you describe or regularly maintained, certainly not
done in advance. Some of that crappy documentation was mine, I'm, sorry to
say.
By the way, the design document also forms an " implementation of
requirements" document, and is usually the basis for my time and cost
estimates.
My experience is that the requirements should actually be the focus, because,
no matter how we try, the design is hard to predict, even in fairly rough
detail, and it's harder to keep up to date than requirements. As much as
possilbe, the design should be made to explain itself.
No coding detail is included, apart from reference to specialised modules,
for some form or report which is dependent on that module. The design
document describes the forest and its blocks, not the individual coding
trees. Anyone who can't recognise a tree should not be messing around in the
forest.
We seem to agree here.
When in full flight, some pages of the design document may be updated and
reprinted three times in one day, simply because the handwritten notes
become too messy. And I want a clear statement of the building to date, on
which the next floor will be built.
But why not type these in as code comments, then write the code following the
comments? If the code is well-structured, the highest-level objects in
hierarchy of abstraction will end up being the broad design description.
All of my applications are installed remotely. The last handful have been
installed in the USA, from New Zealand. It is essential to have a checklist
of the supporting files etc. My agent or principal receives a copy of
updated design documents to help them with installation and maintenance
questions.
Yes. I try to simply avoid the need for supporting files as much as possible.
I'll also try to write code in the app, so it can make the files it needs
rather than distribute them separately. If that fails, I try to keep all
supporting files in a directory tree starting with a subdirectory of the
directory in which the app will be installed, and have the app search that
location relative to itself to find all files. If a supporting file is to be
shared, then I put it relative to the back-end.
This approach suits my skills and shortcomings, and provides a good basis
when revisiting an application, or when another programmer is assisting or
taking over the application.
Well, I imagine we all have similar shortcomings, and just about every
technique or habit we invent is to try to be productive in spite of them, eh?
I always pick up some improved thinking from discussions like this.

Clive

"Steve Jorgensen" <no****@nospam.nospam> wrote in message
news:0h********************************@4ax.com.. .
On Tue, 10 Feb 2004 14:42:57 +1300, "CDB" <al***@delete.wave.co.nz> wrote:
>Apart from VBA comments describing the function of the next segment ofcode, >I gave up most internal documentation. My very strong preference and
>practice for over a decade is to use a design document.


Really? I have yet to see a design document that had much to do with the
state of the application by the time I read it. That makes the design
docunment not much use, though it took someone a lot of time to create. I
have had the idea, recently, to at least maintain a requirements document,

and
never update code prior to updating the requirements, since the purpose of

any
code should be to meet some requirement, or why write it? This also keeps

the
requirements in sync with the program and helps keep development on a

clear
track.

...

I think all these things are important, but I prefer to try to find ways

to
embed them within the application rather than maintaining them separately.
For one thing, they'll be more likely to be maintained because you can't
forget about them - they're right there in the thing you're modifying.

For
another thing, you never need to worry about whether external files have

been
properly kept track of or whether you're looking at the right version for

the
version of the system you're examining..


Nov 12 '05 #13

P: n/a
On 10 Feb 2004 03:20:13 -0800, Pi*************@mail.com (Pink Panther) wrote:
Hi Steve,

Comments inline

Steve Jorgensen <no****@nospam.nospam> wrote in message news:<f2********************************@4ax.com>. ..
On Sun, 8 Feb 2004 16:14:19 +0100, "Jelmer" <jk******@planet.nl> wrote:
For most Access projects, the most important thing to document is the ERD.


Agreed. Very important but oft neglected.

As well as the ERD, a data dictionary I find to be invaluable to get
up to speed on an unfamilar system. I'm maintaining a system which has
over 1000 fields, many of them apparently unused, others named in a
manner which has nothing to do with the actual data stored in the
field. Try to figure out the difference between lngTotal_Sheet and
lngTotal_Worked and lngAll_Worked (argh L/R applied to field names) by
looking at the field names.


I've come to agree on the importance of a data dictionary, though I still have
never created one. I'm hoping to fix that on future projects. I do try to
name things clearly.
Naming you tables and fields properly is a good start to 'documenting'
your system.
I've come up with a handy rule for this. Make the name as short as you can,
and have it be totally obvious what the name means. Sometimes, that's not so
short, but that's OK. Avoid ambigupus abbreviations like the plague. These
include Exp, No, ... Use Exper, Expns, Num, Not, ... instead.
Filling out the description of the field is even better (and it's easy
to write a tool to extract this).
Unfortunately, I find it's easy to lose these attributes in a C/S system
(during relinking, etc.), so I tend to document these in comments in a module,
and use the description properties mainly for forms and reports.
There is an international standard on entity and attribute naming
conventions (Lyle Fairfield posted a link to it, as Joe Celko I
think). Well worth a read.
I'll have to find that link.
To me, the next most important documentation is the in-project documentation.


Code Complete by McConnell has some excellent stuff on in-project
documentation.


Yes, funny I've managed to go so long without reading it, but I happen to be
reading it now.
He calls it self-documentation if I remember correctly. eg name your
procedures etc meaningfully

It's also got great stuff about the size of projects and the amount of
documentation that is 'required' and the overall purpose of
documentation.

The guy before me where I am developed a great system were all changes
need to go through a 'Systems Change Request' process, and the changes
are added to a database, so all the changes to the system are, to some
degree, at least, documented.
That sounds great, but I wonder if that's feasible for us indepentent
developers.
I've inherited systems with thousands of lines of code with a mini
post-it note as the documentation. It's not a good feeling.
Well, unless the code is very self-documenting.
Having said all that I still find myself wrestling with the
documentation monster on a regular basis as personally I find
documentation like flossing one's teeth. You know you've should do it
but it's easy to skip.
I'm getting better since I've started writing my design, first as comments,
then writing the code the comments describe. It's a habit that works.
Visio is an invaluable tool in the wrestling pit IMO.

Reams of documentation of 'this is the print button', 'this is the
next button' etc is IMO a waste of time. It should be bleedin' obvious
to a developer that it's a print button. Equally annoying is

'open report
Docmd.OpenReport "Whatever" <g>
or a 700 line procedure....


Just in the past few months, I've developed a new aesthetic that a procedure
longer than about 25 lines is probably a mess needing immediate clean-up
before coding can continue. That's not to say, I don't have a few 60-line
procedures in recent code, but they're itches that get scratched as soon as I
have a good reason to revisit the code.

Nov 12 '05 #14

P: n/a
Pink Panther wrote:
As well as the ERD, a data dictionary I find to be invaluable to get
up to speed on an unfamilar system. I'm maintaining a system which has
over 1000 fields, many of them apparently unused, others named in a
manner which has nothing to do with the actual data stored in the
field. Try to figure out the difference between lngTotal_Sheet and
lngTotal_Worked and lngAll_Worked (argh L/R applied to field names) by
looking at the field names.


My FindName and FindCode tools anything for you?

--
Bas Cost Budde
http://www.heuveltop.org/BasCB
but the domain is nl

Nov 12 '05 #15

P: n/a
CDB

"Steve Jorgensen" <no****@nospam.nospam> wrote in message
news:gk********************************@4ax.com...
On Wed, 11 Feb 2004 00:15:26 +1300, "CDB" <al***@delete.wave.co.nz> wrote:
....> We seem to agree here.

I am sure we do. ....
But why not type these in as code comments, then write the code following the comments? If the code is well-structured, the highest-level objects in
hierarchy of abstraction will end up being the broad design description.
Because the code is at too fine a level, or is nonexistent. My design
document does not document the code. One key area documents every access
object and its relationship to all other access objects. I find this an
essential aid once an application has 300 or more access objects.
....
Yes. I try to simply avoid the need for supporting files as much as possible. I'll also try to write code in the app, so it can make the files it needs
rather than distribute them separately. If that fails, I try to keep all
supporting files in a directory tree starting with a subdirectory of the
directory in which the app will be installed, and have the app search that
location relative to itself to find all files. If a supporting file is to be shared, then I put it relative to the back-end.


I agree with you concerning an application's own private files and
supporting files in general, but I still get caught with forgetting to check
that eg the MSLDB.USR file is present in the user's system.

Any new requirements, required fixes, improvements, matters for checking,
etc are also noted. During the main development stage of a new application,
all objects that have not completed the initial testing stage are bulleted.
It's a great feeling to see those bullets disappear.

Clive


Nov 12 '05 #16

P: n/a
Hi Bas,

I'm interested in looking at the tools but can't seem to get to them.

IE says

Cannot find server or DNS Error

for your URL http://www.heuveltop.org/BasCB

so not sure what your tools do (though I guess it's similar to Speed
Ferret or somesuch).

If you have time could you zip it and mail it to
pi*************@mail.com? They look useful.

Regards,

Peter

Bas Cost Budde <ba*@heuveltop.org> wrote in message news:<c0**********@news2.solcon.nl>...
Pink Panther wrote:
As well as the ERD, a data dictionary I find to be invaluable to get
up to speed on an unfamilar system. I'm maintaining a system which has
over 1000 fields, many of them apparently unused, others named in a
manner which has nothing to do with the actual data stored in the
field. Try to figure out the difference between lngTotal_Sheet and
lngTotal_Worked and lngAll_Worked (argh L/R applied to field names) by
looking at the field names.


My FindName and FindCode tools anything for you?

Nov 12 '05 #17

P: n/a
Pink Panther wrote:
Hi Bas,

I'm interested in looking at the tools but can't seem to get to them.

IE says

Cannot find server or DNS Error

for your URL http://www.heuveltop.org/BasCB

Please read my signature line again, carefully. :-)

--
Bas Cost Budde
http://www.heuveltop.org/BasCB
but the domain is nl

Nov 12 '05 #18

This discussion thread is closed

Replies have been disabled for this discussion.