Write a module-level documentation comment explaining what this code does for a future maintainer.

← Getting Started · Ref: Q1028

Module: inventory.pricing

Provides price calculation functions for the inventory system. All functions are pure — they compute results from inputs without side effects.

calculateDiscount: Applies a percentage discount to a base price. Returns the discounted price, or the original price if the discount percentage is unset.

applyTax: Adds tax to a price at the given rate. Returns the price with tax included.

formatPrice: Converts a Float price to a display String with two decimal places.

Design notes:
- All functions are marked 'as pure' for thread safety and testability
- Guard expressions handle unset inputs gracefully
- Functions are small and focused — each does one thing
- The module has no state — it is a collection of utility functions

Example

defines module inventory.pricing

  defines function

    <?-
      Applies a percentage discount to a base price.
      Returns the discounted price, or the original if discount is unset.
    -?>
    calculateDiscount() as pure
      ->
        basePrice as Float
        discountRate as Float
      <- rtn as Float: basePrice

      if discountRate?
        rtn := basePrice - (basePrice * discountRate)

    <?-
      Adds tax to a price at the given rate.
    -?>
    applyTax() as pure
      ->
        netPrice as Float
        taxRate as Float
      <- rtn as Float: netPrice + (netPrice * taxRate)

    <?-
      Converts a price to a display string.
    -?>
    formatPrice() as pure
      -> amount as Float
      <- rtn as String: `${amount}`

  defines program

    PricingDemo()
      stdout <- Stdout()

      basePrice <- 100.0
      discountRate <- 0.15
      taxRate <- 0.20

      discounted <- calculateDiscount(basePrice, discountRate)
      withTax <- applyTax(discounted, taxRate)
      stdout.println(`Price: ${formatPrice(withTax)}`)

Common mistakes

E11031 — Generic non-descriptive variable names like 'data' are banned; use a meaningful identifier such as 'discounted'. See ek9 -h E11031 for details.

Incorrect:

      data <- calculateDiscount(basePrice, discountRate)
      withTax <- applyTax(data, taxRate)

Correct:

      discounted <- calculateDiscount(basePrice, discountRate)
      withTax <- applyTax(discounted, taxRate)
Other ways to ask this
  • Document this EK9 module for someone reading it in 6 months
  • Write a description of this module's purpose and design
  • Explain this code for documentation purposes

Coming from another language?

EK9 documentation describes what the code does, its design decisions, and how to use it — without comparing to other languages.

Keywords: maintainer, explain, module, document, purpose