Use Comments to Identify Yourself and Your Purpose in Quick Base Formula Fields

"Code is read far more times than it's written, even during initial development. Favoring a technique that speeds write-time convenience at the expense of read-time convenience is a false economy."
Steve McConnell
Code Complete: A Practical Handbook of Software Construction

Quick Base formula fields allow developers to leave comments in the formula. Just prefix any comment with a double slash. Anything that follows after the double slashes to the end of the line will be treated as a comment:

// This formula will calculate the sales tax to be collected
[Subtotal] * [Sales Tax Rate] // Here's another comment

Why go to all this trouble?

At Watkyn, our practice is to start a formula field with comments identifying which one of us made the field, on what date, and for what purpose, as in the example above.

Adding comments to the start of a formula really isn’t any trouble at all. The exercise of stating succinctly why you need to create this formula field will help to crystallize your thinking. More than once while trying to explain the field’s purpose, we’ve come to realize we actually didn’t need a new field at all. Delete.

It's a good practice to add comments to Quick Base formula fields

The most important reason

The most important reason for these comments, however, are to provide a written record for yourself and other developers in the future. If this is important in any kind of software development, it’s even more important in Quick Base and other citizen developer contexts. There are several reasons for this:

  • Tables in Quick Base tend to grow and grow and grow. People create fields just to show a column in an ad hoc report that was run once in 2008 – but the field sits there forever, gathering moss. When a future developer comes along, it can take a lot of work to figure out why a particular field exists and whether it’s still needed. And even if you think you know, there’s always that lingering uncertainty.
  • Later development and new Quick Base features make some older formula fields obsolete. As you build out and extend your app, you will inevitably find new and better ways of accomplishing something in the app than you were doing before. You used to have two sales tax rate fields in each order record, one for the state and one for the county rate, and formula fields that would calculate the sales tax amounts. Later, you migrated that function to a Sales Tax Rates table and other supporting tables but forgot to delete the old obsolete fields.
If this is important in any kind of software development, it's even more important in Quick Base and other citizen developer contexts.

By starting off each new formula field with a simple comment identifying yourself as the creator and your reason for creating this new field, you will save yourself and other developers in the future the wasted time and uncertainty of trying to figure out why this field exists and whether it’s still needed.

More best practices

Two other kinds of preliminary comments that may be helpful are these:

  • Your contact information. If you’re a developer in an enterprise or large organization, you might also consider leaving your phone number, extension, or mail stop, to save someone the trouble of tracking you down later on if there are unresolved questions.
  • Delete after. Another good practice is to leave a “Delete after” comment if this field is only needed for a specific temporary report you’re creating. If someone sees your field that says “Delete after 5/15/2013,” followed by a quick description of the ad hoc report you made the field for, they’ll quickly be able to determine if it needs to stay or should go.

Remember, these are only suggestions for preliminary comments at the top of a formula field, to identify the author and purpose. We also recommend leaving explanatory comments in the body of the formula to help others understand the logic.

Leave a Reply