Uploaded image for project: 'FHIR Specification Feedback'
  1. FHIR Specification Feedback
  2. FHIR-27073

Consider simplifying first aggregate example

    XMLWordPrintableJSON

Details

    • Icon: Change Request Change Request
    • Resolution: Persuasive
    • Icon: Medium Medium
    • Clinical Quality Language (FHIR)
    • 1.5
    • Clinical Decision Support
    • Developers Guide
    • 12. Aggregate Queries
    • Hide

      Agreed, replace the current Factorial example with the suggested example and update text appropriately.

      Note that the example is FactorialOneToFive, a general Factorial could be defined using the expand operator to generate the sequence of integers through the input argument.

      Show
      Agreed, replace the current Factorial example with the suggested example and update text appropriately. Note that the example is FactorialOneToFive, a general Factorial could be defined using the expand operator to generate the sequence of integers through the input argument.
    • Chris Moesel/Paul Denning: 12-0-0
    • Enhancement
    • Non-substantive

    Description

      The first aggregate example is

      define function Factorial(X Integer):
        (expand Interval[1, X]) R
          aggregate T: Coalesce(T, 1) * R 

      While this is pretty simple, there are a few things that aren't immediately obvious upon first read:

      • What does R stand for? At first I thought "Result" but that definitely set me off on the wrong foot when trying to understand the query because R is definitely not the result of the aggregation in this case.
      • What does T stand for? Is it "Total"? In some aggregations (like summations) that makes sense, but maybe not in a factorial?
      • What does T actually do?  Since the syntax of aggregation hasn't been introduced, the reader needs to try to figure out what the argument after "aggregate" actually means.
      • What's that Coalesce there for?  I know it's because T is null the first time, but I had to think about it.  Wouldn't "starting 1" be the recommended approach?

      In addition, using expand Interval[1,X] complicates the example since the author needs to remember how expand works with intervals when no per is specified...

      So... since this is the first introduction of aggregate, I think it makes sense to make the example as simple as possible while also following recommended practices.  To that end, I'd suggest something more like:

      define function FactorialOneToFive:
        ({1,2,3,4,5}) Num
          aggregate Result starting 1: Result * Num 

      If you want to encourage single character aliases, then I'd use N and R as someone might be able to guess number and result.

      Attachments

        Activity

          People

            bryn.rhodes Bryn Rhodes
            cmoesel Chris Moesel
            Watchers:
            3 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved: