Successful Commenting in FileMaker
The Use of Comments in FileMaker
As a FileMaker developer I often need to preserve notes regarding some specific aspect of a database. These comments might concern how a relationship works, or why I've got a hidden object on a layout or even the function of a table. FileMaker provides lots of tools for these 'developer only' notes but there are a few places where FileMaker could do better and that's where we need to be a little more creative.
All fields have a comment section so you can record whatever you want here. I always include my initials and usually the date (handy when more than one developer is working on a database). You can even grab the field comment and view it via a script using the FieldComment command - this can be particularly handy if you have a lot of similarly named fields and want to remind yourself what they all are. For example, if you add this as a tooltip for each field:
If ( Get ( AccountPrivilegeSetName ) = "[Full Access]" ; FieldComment ( Get ( FileName ) ; GetFieldName ( Self ) ) )
You'll be able to view the field comment when logged in with Full Access rights. Very handy in the right situation.
We've got field comments but no table comments? Come on FileMaker, surely that's a no brainer? In any case, I get around this by recording all of my table notes in the comment section of the table's primary ID field. It's not often that I need to do this but there are times when need to explain what a table does so that the future me has something to go on rather than having to waste time pondering.
Well here we have the excellent text box tool which means we've got plenty of comment control. We can set font, size, colour and background colour. You can place the text box under entities/relationship links to highlight specific aspects of the relationship diagram. I usually add a long thin text box indicating the lower limits of the RD.
It's not often that I have a calculation which is so complicated that I feel the need to break it down but it does happen and in these cases, comments are a must. Use either // or /* */ to get your point across.
With scripts we have the Comment command which is the best way to add detailed comments about what the script does, how a section of the script works and so on. Despite this simple feature, I frequently work on databases where developers have neglected to use any script comments - this is a heinous offence, really truly awful!
I always use comments to record who created the script and when, what the script is meant to do, a list of parameters (if required) and then list the latest notes (changes and the like). The last comment section is very useful when working on databases over a long period, though it tends to get used less with a database which is in development.
Here's an example of a script header :
Created By : Jon - 01/01/2012
Purpose : Prints stock report
Parameters : Date range
Latest Notes : Jon - 04/04/2014 - Included check for new report.
When I need to make changes to a database, I like to preserve database elements rather than delete/change them. What I mean by this is if a client wants a major alteration to a layout, I'll duplicate the layout, alter the layout name so that it includes my initials and the date and preserve it in a legacy layout folder. I do the same for scripts as well. Sure, if I made a mistake I could always grab a backup copy but for me, using a backup indicates a failure in the development process - besides, it's a lot slower.
Of course, sometimes you might make a change to a layout which really doesn't warrant an entire layout backup but you'd still like to keep a copy of your natty little layout object. It's easy enough to grab that object and move it off the layout so that no one sees it, but over time, these hidden objects can make for quite a bit of mess. What I like to do is to create a tab section, off screen so to speak, and place all of these objects in their own tab, which helps to keep everything neat and accessible should you need it.
So where do comments come in? Well I use the first tab to hold a text object for recording the layout comments. Sure, this isn't required for each and every layout, but for some of the more unusual layouts, recording why you've taken a particular approach can be a serious time-saver for the future you.
Remember that in database development, consistency is key. It should be your developer mantra as following that maxim makes for speedier, more accurate database design/creation and that can only ever be a good thing.