documenting access apps

[Jelmer]

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

[Scott McDaniel]

Re: documenting access apps

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" <jkuperus@plane t.nl> wrote in message
news:c05jto$m3k $1@reader10.wxs .nl...[color=blue]
> 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[/color]
you[color=blue]
> people document your access apps?
> Just create an ERD and have comments in the vba code? List all the forms[/color]
and[color=blue]
> it's purpose ?
> Are there any methodologies / best practices / examples I can look at?
> thanks in advance
>
> -- jelmer
>
>[/color]

[NB]

Re: documenting access apps

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

[Bas Cost Budde]

Re: documenting access apps

Jelmer wrote:
[color=blue]
> 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?[/color]

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.
[color=blue]
> 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[/color]

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

[Bas Cost Budde]

Re: documenting access apps

NB wrote:
[color=blue]
> 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[/color]

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

[Steve Jorgensen]

Re: documenting access apps

On Sun, 8 Feb 2004 16:14:19 +0100, "Jelmer" <jkuperus@plane t.nl> wrote:
[color=blue]
>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
>[/color]

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.

[CDB]

Re: documenting access apps

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" <nospam@nospam. nospam> wrote in message
news:f2ne20la33 t83tvffhkseteru k6bra86oq@4ax.c om...[color=blue]
> On Sun, 8 Feb 2004 16:14:19 +0100, "Jelmer" <jkuperus@plane t.nl> wrote:
>[color=green]
> >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[/color][/color]
you[color=blue][color=green]
> >people document your access apps?
> >Just create an ERD and have comments in the vba code? List all the forms[/color][/color]
and[color=blue][color=green]
> >it's purpose ?
> >Are there any methodologies / best practices / examples I can look at?
> >thanks in advance
> >
> >-- jelmer
> >[/color]
>
> 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[/color]
Micheal[color=blue]
> 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[/color]
documentation.[color=blue]
> The documentation is both more clear in meaning and more likely to be[/color]
properly[color=blue]
> maintained if it is located right with the thing it documents. In fact,
> documentation outside the system is usually not maintained, and becomes[/color]
worse[color=blue]
> than useless in no time. Documentation inside the system can be printed[/color]
using[color=blue]
> 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[/color]
thing[color=blue]
> 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[/color]
used[color=blue]
> within other objects with a Dash, and add more dashes for more deeply[/color]
nested[color=blue]
> 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[/color]
that[color=blue]
> will use it. Documentation function rather than purpose/usage will be out[/color]
of[color=blue]
> 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[/color]
in[color=blue]
> popup menus, event properties, etc. You can uses database documenters to[/color]
see[color=blue]
> 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[/color]
objects'[color=blue]
> code modules.[/color]

[Steve Jorgensen]

Re: documenting access apps

On Tue, 10 Feb 2004 14:42:57 +1300, "CDB" <alpha@delete.w ave.co.nz> wrote:
[color=blue]
>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.[/color]

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.
[color=blue]
>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.
>
>Relationship s. 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[/color]

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.

[Bas Cost Budde]

Re: documenting access apps

Steve Jorgensen wrote:
[color=blue]
> 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.[/color]

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

[Steve Jorgensen]

Re: documenting access apps

On Tue, 10 Feb 2004 08:47:19 +0100, Bas Cost Budde <bas@heuveltop. org> wrote:
[color=blue]
>Steve Jorgensen wrote:
>[color=green]
>> 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.[/color]
>
>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'
>documentatio n first (even sketch-like) that will improve the
>synchronizatio n.[/color]

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.

[CDB]

Re: documenting access apps

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" <nospam@nospam. nospam> wrote in message
news:0heg20hg60 kt95e0geo1vbepb vqplcb4la@4ax.c om...[color=blue]
> On Tue, 10 Feb 2004 14:42:57 +1300, "CDB" <alpha@delete.w ave.co.nz> wrote:
>[color=green]
> >Apart from VBA comments describing the function of the next segment of[/color][/color]
code,[color=blue][color=green]
> >I gave up most internal documentation. My very strong preference and
> >practice for over a decade is to use a design document.[/color]
>
> 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,[/color]
and[color=blue]
> never update code prior to updating the requirements, since the purpose of[/color]
any[color=blue]
> code should be to meet some requirement, or why write it? This also keeps[/color]
the[color=blue]
> requirements in sync with the program and helps keep development on a[/color]
clear[color=blue]
> track.[/color]
....[color=blue]
>
> I think all these things are important, but I prefer to try to find ways[/color]
to[color=blue]
> 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.[/color]
For[color=blue]
> another thing, you never need to worry about whether external files have[/color]
been[color=blue]
> properly kept track of or whether you're looking at the right version for[/color]
the[color=blue]
> version of the system you're examining..[/color]

[Pink Panther]

Re: documenting access apps

Hi Steve,

Comments inline

Steve Jorgensen <nospam@nospam. nospam> wrote in message news:<f2ne20la3 3t83tvffhkseter uk6bra86oq@4ax. com>...[color=blue]
> On Sun, 8 Feb 2004 16:14:19 +0100, "Jelmer" <jkuperus@plane t.nl> wrote:[/color]
[color=blue]
> For most Access projects, the most important thing to document is the ERD.[/color]

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.
[color=blue]
> To me, the next most important documentation is the in-project documentation.[/color]

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.OpenRepor t "Whatever"

or a 700 line procedure....

Peter

[Steve Jorgensen]

Re: documenting access apps

On Wed, 11 Feb 2004 00:15:26 +1300, "CDB" <alpha@delete.w ave.co.nz> wrote:
[color=blue]
>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.[/color]

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.
[color=blue]
>By the way, the design document also forms an " implementation of
>requirements " document, and is usually the basis for my time and cost
>estimates.[/color]

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.
[color=blue]
>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.[/color]

We seem to agree here.
[color=blue]
>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.[/color]

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.
[color=blue]
>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.[/color]

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.
[color=blue]
>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.[/color]

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.
[color=blue]
>
>Clive
>
>"Steve Jorgensen" <nospam@nospam. nospam> wrote in message
>news:0heg20hg6 0kt95e0geo1vbep bvqplcb4la@4ax. com...[color=green]
>> On Tue, 10 Feb 2004 14:42:57 +1300, "CDB" <alpha@delete.w ave.co.nz> wrote:
>>[color=darkred]
>> >Apart from VBA comments describing the function of the next segment of[/color][/color]
>code,[color=green][color=darkred]
>> >I gave up most internal documentation. My very strong preference and
>> >practice for over a decade is to use a design document.[/color]
>>
>> 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,[/color]
>and[color=green]
>> never update code prior to updating the requirements, since the purpose of[/color]
>any[color=green]
>> code should be to meet some requirement, or why write it? This also keeps[/color]
>the[color=green]
>> requirements in sync with the program and helps keep development on a[/color]
>clear[color=green]
>> track.[/color]
>...[color=green]
>>
>> I think all these things are important, but I prefer to try to find ways[/color]
>to[color=green]
>> 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.[/color]
>For[color=green]
>> another thing, you never need to worry about whether external files have[/color]
>been[color=green]
>> properly kept track of or whether you're looking at the right version for[/color]
>the[color=green]
>> version of the system you're examining..[/color]
>[/color]

[Steve Jorgensen]

Re: documenting access apps

On 10 Feb 2004 03:20:13 -0800, PinkPanther2003 @mail.com (Pink Panther) wrote:
[color=blue]
>Hi Steve,
>
>Comments inline
>
>Steve Jorgensen <nospam@nospam. nospam> wrote in message news:<f2ne20la3 3t83tvffhkseter uk6bra86oq@4ax. com>...[color=green]
>> On Sun, 8 Feb 2004 16:14:19 +0100, "Jelmer" <jkuperus@plane t.nl> wrote:[/color]
>[color=green]
>> For most Access projects, the most important thing to document is the ERD.[/color]
>
>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_Worke d and lngAll_Worked (argh L/R applied to field names) by
>looking at the field names.[/color]

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.
[color=blue]
>Naming you tables and fields properly is a good start to 'documenting'
>your system.[/color]

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.
[color=blue]
>Filling out the description of the field is even better (and it's easy
>to write a tool to extract this).[/color]

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.
[color=blue]
>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.[/color]

I'll have to find that link.
[color=blue][color=green]
>> To me, the next most important documentation is the in-project documentation.[/color]
>
>Code Complete by McConnell has some excellent stuff on in-project
>documentatio n.[/color]

Yes, funny I've managed to go so long without reading it, but I happen to be
reading it now.
[color=blue]
>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
>documentatio n that is 'required' and the overall purpose of
>documentatio n.
>
>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.[/color]

That sounds great, but I wonder if that's feasible for us indepentent
developers.
[color=blue]
>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.[/color]

Well, unless the code is very self-documenting.
[color=blue]
>Having said all that I still find myself wrestling with the
>documentatio n monster on a regular basis as personally I find
>documentatio n like flossing one's teeth. You know you've should do it
>but it's easy to skip.[/color]

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.
[color=blue]
>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.OpenRepo rt "Whatever"[/color]
<g>
[color=blue]
>or a 700 line procedure....[/color]

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.

[Bas Cost Budde]

Re: documenting access apps

Pink Panther wrote:
[color=blue]
> 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.[/color]

My FindName and FindCode tools anything for you?

--
Bas Cost Budde

http://www.heuveltop.org/BasCB

but the domain is nl