1 2 3 Previous Next 38 Replies Latest reply on Mar 9, 2017 1:29 AM by MacDevGuy

    Describing Well Documented

    BruceRobertson

      Will I know it when I see it?

       

      I'd like to see examples and discussion of the subject of "well documented files."

       

      Many discussions here refer to solutions that are not well documented.

       

      Many statements here declare that the example files which come with FileMaker are NOT well documented.

       

      But what are we looking for?

      I'd like to see some examples of files that are rated as well documented.

       

      Of course this is open to a lot of interpretation.

      There are probably examples that are sparsely documented, but nevertheless use clear naming conventions.

      I'm sure there are examples that are exhaustively documented.

       

      Can we describe what we're looking for?

      Can you post file names, or links, or actual files, which provide useful examples?

       

      I am posting this topic as a question because that allows contributors to post example files.

       

      I may or may not ever declare the question as "answered" because of course there won't be one best example.

      But I may declare it "answered" after we have received a good range of examples.

        • 1. Re: Describing Well Documented
          jfletch

          Very good question, Bruce. I'd like to see what other people are doing, too. To start it off, I have a few things that are standard for me, but are, of course, in no way the last word on the subject.

           

          SCRIPTS

          1. Use a script template that has a format at the top for things that matter to the script:

               a. Short statement of purpose

               b. Parameters and their purposes

               c. Further explanation of the script as necessary

               d. Dependencies (CFs, subscripts, plugins, etc.)

               e. Creation and change log

           

          2. The SECOND thing you do after the top documentation is to write what you are going to do in the script in a series of double spaced script lines.

           

          3. Fill in your script steps below the documentation narrative lines leaving plenty of extra lines as white space to set of sections and grouping of steps.

           

          4. Add any further notes as needed for things that might not be obvious when you are back in the script two years from now, or two months, or two weeks, or two days, or...

           

          5. If you are going to make massive changes to a script (the threshold of "massive" is up to the individual) duplicate it, label the COPY as DEPRECATED with your initials and the date and stick it in a deprecated folder. This way you can refer back to it later if you need to.

           

          FIELDS

          1. Nomenclature, nomenclature, nomenclature

          2. Use a delimiter (underscore or dot) to append a functional specific about the field that is different than merely its contents ( fieldName.entry, fieldName.display, fieldName.filter, etc. )

          3. Calcs: use LET a LOT in complex calcs. with totally understandable variable names. Build up complex calcs in stages to make them more accessible and easier to troubleshoot.

           

           

          TABLES and TOs

          1. Nomenclature also big here

          2. Also use a table template that has all the "housekeeping" fields already in place.

          3. Underscores between table path names

          4. Dots for functional detail (appended, NOT prepended)

           

          That's SOME things. The details are less important, though, than these three things:

          1. Verbosity

          2. Transparency

          3. Slavish/OCD/AR attention to consistency

           

          That's off the top of my head. I would love to hear others chime in!

          1 of 1 people found this helpful
          • 2. Re: Describing Well Documented
            philmodjunk

            I do something very close to JFletch's methods, but to that I also use text boxes to document my relationship graph.

             

            And then hen there is the need to document your interface design:

             

            The same needs hold true for layouts. Today's layouts often contain elements that are not visible or who's function is not obvious.

             

            Layout text explaining such features can either be placed off the edge of the layout or given the simple Hide Object When expression of True to make it invisible when in Browse mode.

             

            I have lately taken to using a help window system where clicking a button opens a window listing help topic titles in a portal on slide control moves the 2nd panel to the front and displays the topic's article in that panel. In this tool I now include "design notes" only visible to developers that document design features of the current layout.

             

            Not only does this give me an easy place to document unusual layout features, but the combination of user instructions and developer notes  produce a pretty complete picture of the interface design.

            • 3. Re: Describing Well Documented
              philmodjunk

              After reading these posts, open one of the starter solutions and see what they do. The near total lack of any documentation of any kind is appalling.

              • 4. Re: Describing Well Documented
                BruceRobertson

                OK; compared to what?

                I have generally found them mostly self explanatory and often find the supposedly valuable headers in other files still leave me reading through script detail anyway.

                I do find many of the template field names like CUSTOMER MATCH FIELD pretty dreadful though.

                I am asking myself, give me a template file I have never seen before (well, impossible now) and one of your files, what is the differential in time I would spend to feel like OK, I got it now?

                • 5. Re: Describing Well Documented
                  philmodjunk

                  Compared to solutions with documentation. Do you find comments in the scripts? ANY comments at all?

                  Remember that these "self explanatory" scripts get opened by people very new to FileMaker and Relational Databases who won't find them as obvious as you and I might. 

                   

                  And I get real irritated having to play detective, tearing layouts apart or running scripts in the debugger just to figure out that they, for example, put a slide control inside a popover and hid the navigation dots when a bit of documentation would have saved me the trouble. Now imagine someone new to FileMaker trying to puzzle that out.

                   

                  Keep in mind that these starter solutions serve as examples of

                  a) what can be done with FileMaker--done

                  b) good interface design--done

                  c) good database design to--not done due to missing documentation

                   

                  to people very new to database design.

                  • 6. Re: Describing Well Documented
                    planteg

                    Now imagine someone new to FileMaker trying to puzzle that out.

                     

                    Exactly. And one can add: imagine someone else going through your design and trying to figure out what you have done. Even one can be lost in it's own design  a year after.

                    1 of 1 people found this helpful
                    • 7. Re: Describing Well Documented
                      jfletch

                      Or a couple days...

                       

                      I document for ME!

                      • 8. Re: Describing Well Documented
                        philmodjunk

                        "I document for ME!"

                         

                        Likewise, and also for fellow developers, both current and future.

                        • 9. Re: Describing Well Documented
                          jfletch

                          I'm not saying I am selfish, but that I need the most help! 

                          • 10. Re: Describing Well Documented
                            beverly

                            Consider: if you create an outline of what a script does and make it comments in the script, then you probably have well planned and are less likely to make mistakes when you "flesh out" the script with actual steps afterwards.

                             

                            Sent from miPhone

                            1 of 1 people found this helpful
                            • 11. Re: Describing Well Documented
                              BMyers

                              Yes, Beverly, I've found that very handy.  I use a template script format that DB Solutions uses.  It has sections for the context, purpose, then variables and parameters at the top.  Then I write the steps in a combination of english and pseudocode.  Then I go back and write the script steps and calcs.  The english/pseudocode then becomes the comments.  This seems efficient (for me anyway).

                              • 12. Re: Describing Well Documented
                                coherentkris

                                I would consider a solution well documented when:

                                a. cf's & scripts have headers that contain notes to hep someone understand the purpose and actions especially stuff that's not blatantly obvious i.e recursion.

                                b. When an object (script/layout,table/to/field et al) naming convention is documented, implemented, and exceptions are noted

                                c. CRUFT that naturally occurs and not yet removed is annotated.

                                d. non normalized structures ( i.e use of a heiearchical table to store BOM items ) are well documented somewhere.

                                e. All customer requirements, solution related business processes, and DB design decisions are documented in an external document.

                                f. Any external component dependencies ( plug ins, OS scripts, server side processes) are documented

                                g. references to complex (for the beginner) implemented techniques i.e virtual list.. et al are documented

                                • 13. Re: Describing Well Documented
                                  IanJempson

                                  I've changed my opinions on what "well documented" means over the years. I started out thinking along the same lines as much of what's been posted already. In the office we'd have a meeting and everyone would agree that's what we're going to do and it lasts all of ten minutes. Nobody ever updates that kind of documentation. You end up with a divergence of the requirements, code, and comments. At which point the comments are worse than useless - they're now one of the problems to be dealt with. How many times have you read a comment that restates what's inside the IF statement it precedes? How many times does it describe something that almost exactly the same but ever so slightly different from the content of the IF statement?

                                   

                                  Lately I've been much more influenced by Martin Fowler's superb book on refactoring. It's not aimed at FileMaker but it's worth reading. Code should be readable. Code should be expressive of intent. When it's well written you don't need loads of comments cluttering up the place.

                                   

                                  What we've got are up to date process flows and documents outside FileMaker and relatively little documentation inside FileMaker. Scripts are named with descriptive names that fit with the external documentation. A lengthy comment is usually a clear sign that you should refactor that chunk of code into a separate properly named script. A properly named subscript will remove the need for additional comments in many cases. Comments are frequently used as a pointer to the external documentation. Variables have clear descriptive names, likewise Extended Privileges. Coding in this manner also has the massive benefit that we can write a nice test harness and do proper automated testing.

                                   

                                  This of course describes the new development! The bulk of our live system is ancient and convoluted and a total rewrite would be best, but is not going to happen as FileMaker is now viewed as a legacy system. So instead of that it's an extended process of refactoring which we're doing bit by bit.

                                  1 of 1 people found this helpful
                                  • 14. Re: Describing Well Documented
                                    beverly

                                    ditto. no need to clutter with comments if the code is good. I was making note that sometimes setting up the flow can be done with comments and fill-in with steps. I find it better to do this IN FileMaker instead of whiteboard, paper, or app that does this sort of thing.

                                    I might 'rough-out' all the scripts and have to step away (for days, weeks, months). The outlines are very helpful when starting/finishing the "coding" parts later.

                                    1 2 3 Previous Next