Results 1 to 10 of 10

Thread: Documentation

  1. #1
    Join Date
    May 2005
    Posts
    1,191

    Unanswered: Documentation

    I've heard that documentation is very important, but I'm not sure if what I do is sufficient enough or not. So I was wondering if you some of you veteran programmers can tell me what you do for documentation on your Access projects, or if you have any specific tips that you've learned over the years. I appreciate any input you guys have to offer.
    Me.Geek = True

  2. #2
    Join Date
    Jun 2005
    Location
    Richmond, Virginia USA
    Posts
    2,763
    Provided Answers: 19
    The purpose of documentation, of course, is to provide insight into exactly what a piece of code does. It's important when working as part of a team developing a program/application, to another developer who may have to modify/troubleshoot your code at a later date, and to yourself at a later date as well! I go back sometimes and look at old code I've written, and think to myself "What in the world does this code do?" Also keep in mind that the next person to work on your code may have a great deal less experience/ability than you do!

    I think the single, easiest thing you can do is resist taking shortcuts that may save you the typing of a few lines of code, but make your code more cryptic.

    Say that you want to make a textbox only Visible if a checkbox has been checked, otherwise you want it to be invisible.

    This code will accomplish the job:
    Code:
    Private Sub Form_Current()
      MyTextBox.Visible = MyCheckBox
    End Sub
    but it's rather cryptic; what it does would not be readily apparent to everyone.

    This, on the other hand, requires a few more lines of code, but makes the code's purpose much cleaere.
    Code:
    Private Sub Form_Current()
    If Me.MyCheckBox = True Then
      MyTextBox.Visible = True
    Else
      MyTextBox.Visible = False
    End If
    End Sub
    Likewise, the use of things like the Select Case construct makes scanning and understanding code relating to a large number of conditional events much easier than reading half a page or more of If...Then statements.
    Hope this helps!

    The problem with making anything foolproof...is that fools are so darn ingenious!

    All posts/responses based on Access 2003/2007

  3. #3
    Join Date
    Jul 2003
    Location
    Michigan
    Posts
    1,941
    Best practice...

    If building a business critical app for your company, don't do any documentation. It makes it that much harder for them to replace you!

    It's worked for me for 15 years!
    Inspiration Through Fermentation

  4. #4
    Join Date
    Dec 2004
    Location
    Connecticut
    Posts
    85
    As far as I'm concerned, there is no such thing as too much documentation. You will never get in trouble for putting too many comments in your code.

    What is enough depends on a lot of factors. How complex is the activity? Is what happens obvious to the casual user? Am I the only one who knows how to do this? Will the procedure outlast the current users? Will I have to modify it later, when I've forgotten what it does and why? How long will I be doing this before I move on? How often does the client update\upgrade\shift technology?

    The less formal the organization, the more documentation you'll need to give. In big operations where there's a staff of programmers, they develop a style manual that gives lots of direction about the naming conventions and coding styles in use. They develop this after spending too much time trying to interpret other people's undocumented code.

    In a small operation, you'll have to provide everything. If you give them more than they expected, and make them look like they know what they're doing, they recommend you to their freinds.

  5. #5
    Join Date
    Jun 2005
    Location
    Richmond, Virginia USA
    Posts
    2,763
    Provided Answers: 19
    How complex is the activity? Am I the only one who knows how to do this? Will I have to modify it later, when I've forgotten what it does and why?
    Along with these factors, how long did it take me to write this hack? If it took a large chunk of time to develop the original code, it'll probably take a large chunk of time to write it again or modify it, especially if your original logic isn't obvious.
    Hope this helps!

    The problem with making anything foolproof...is that fools are so darn ingenious!

    All posts/responses based on Access 2003/2007

  6. #6
    Join Date
    Feb 2004
    Location
    One Flump in One Place
    Posts
    14,912
    I now work for an ISO9001 accredited company and have really had my eyes opened about how rich a well implented QA process really is. Documentation is just one cog in the whole wheel.

    I would add that documentation does not just extend to annotated & standardised code. In particular, when new to an organisation an overview document, outlining the business processes, models & rules that apply to an application is absolutely invaluable. You can employ programmers who can read & interpret code very quickly but you are very unlikely to get someone who understands not just the general business you are in but also the specifics of how and why you conduct your business. At the simplest level - how many TLAs do you regularly use in your day to day working life? A glossary of the most crucial of these is like gold in your first few weeks and can save a lot of confusion.

    When I was a single bod, over worked and underpaid, this sort of stuff was just too far down the priorities list to do properly. Working somewhere that values these things and drives quality consistently with a good department, thorough procedures and regular audits really has opened my eyes. If you are in this sort of environment, or have the freedom to pursue your own quality measures, then defo go for it.
    Testimonial:
    pootle flump
    ur codings are working excelent.

  7. #7
    Join Date
    Jan 2007
    Location
    UK
    Posts
    11,434
    Provided Answers: 10
    Hasn't ISO14001 just been released?

    Personally:
    Document the design BEFORE you do anything.
    Comment your code extensively during/post development
    Then if you have the time it's always nice to have a formal document with all the information about a system filed nicely away on a shared network resource
    George
    Home | Blog

  8. #8
    Join Date
    May 2005
    Posts
    1,191
    Thanks everyone for your input! I was just mostly looking to see what everyone else was doing. I appreciate it!
    Me.Geek = True

  9. #9
    Join Date
    Nov 2004
    Location
    out on a limb
    Posts
    13,692
    Provided Answers: 59
    Quote Originally Posted by georgev
    Hasn't ISO14001 just been released?

    Personally:
    Document the design BEFORE you do anything.
    Comment your code extensively during/post development
    Then if you have the time it's always nice to have a formal document with all the information about a system filed nicely away on a shared network resource
    1400x has been around for a good few years.... at least 2 or 3. it aint the same thing as 900x (or as we oldies like to call it [BSI] 5750). 14001 is more an environmental standard, whereas 5750 which became 900x is a quality standard. colloqually I've heard 1400x (or as we BSI oldies like to call it...8555) called the tree hugger standard

    documentation is always a difficult juggling act
    I don't think you can ever have too much, but when you need it its nearly always screeds of meaningless verbiage. its never detailed enough for the problem you are trying to resolve right here, right now.

    in terms of program design and coding, then a great deal of the documentation can derive straight from the design (naming of objects, classes) and coding style, some styles are transparent and easy to red, some aren't... just go back to code you wrote 3..5 years ago and see how it reads. see if there are nay comments explaining why you did some whizzo trick. there are some tools (admittedly not int he VBA market, at least as far as I know, that claim to be able to read the code, extract classes, strip out comments. Ive used them in VB.NET & PHP, although not perfect they do go part way to making it easier to understand how things interrelate, and they are no better than the time and effort you put into documenting as you go along.

    it also helps to flesh out a testing harness whilst develoiping, agian Ive not seen one in VBA but they exist in C# & VB in .NET, and on ruby
    Last edited by healdem; 07-30-07 at 11:36.
    I'd rather be riding on the Tiger 800 or the Norton

  10. #10
    Join Date
    Dec 2004
    Location
    Madison, WI
    Posts
    3,926
    There are 2 kinds of documentation. 1 for the coding (technical), and 1 for the user.

    Since I am changing stuff during the design of the database and code, I will add quick comments as I work on the design but I don't get too in-depth (for example, why have a page of documentation for a simple For/Next loop.) Or why design a whole set of in-depth documentation for everything when things will usually change? I will start with some basic documentation on the flow (I use Visio which works great for flowcharting), and then take it from there. I've seen developers spend weeks constructing documentation for a few lines of code which any half-way descent programmer could figure out. After I'm completely done with the code, I'll go through it a second time and document the code a little more thoroughly. healdem brought up a great point - Keep your tables, fields, query names, form names, reports, etc. very close to what they represent. For example, having a field named: Date means nothing whereas a field named: DateEntered makes a lot more sense. And a function called: Admin verses a function called: IsAdminUser() also makes more sense.

    The BIGGEST thing I do which makes it very easy for designing is I like to make my table/form names so they appear in order. Ie...tblContracts, tblContractsAgencies, tblContractsDocuments, tblContractsChecklist, etc... and Forms...frmContracts, frmContractsAgencies, frmContractsDocuments, frmContractsDocumentsSub, etc.. This makes it extremely easy to see how things flow.

    I also try to design the interfaces to be extremely easy to use so there's not a book to read to understand how to use the application. This is very important as most users don't want to read a book to use their application.
    Last edited by pkstormy; 07-30-07 at 13:08.
    Expert Database Programming
    MSAccess since 1.0, SQL Server since 6.5, Visual Basic (5.0, 6.0)

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •