NFFinexec: Style

Finexec | Library | Documentation | Usage | Style

The styles and conventions used to document the Finexec scripts and definitions are set out below.
The scripts are documented using the ~addons/docs/joxygen/joxygen.ijs addon package which creates htm files from the script. For details see: Joxygen

Example: category documentaion:Finexec Category: Basic Finance
Example: script source documentation style: finexec/basicfinance/simple.ijs
Example: script documentation: finexec/basicfinance/docs/simple.htm

Caterory

The category documentaion provides:
1) details of the subject and tasks covered in the category
2) list of scripts in the category 
3) list of definitions in the category

Scripts

As a general style the Finexec scripts are stand-a-lone (ie. no dependencies)
Any dependencies to other scripts are listed at the start of the script.
Use the require definition to load any dependant scripts to aviod having to 
reload the script. 
The definitions from a script are loaded into the locale base unless otherwise indicated in the script.
The documentation for the definitions in a script can be viewed by linking to a script.
The scripts can be used for projects and jobs.
The scripts can copied, modified and loaded into another locale for a project or job to aviod
potential naming conflicts.
View Source Script
The source script can be viewed in Qt and JHS IDE front ends.
eg: Qt IDE: open '~addoms/finance/finexec/basicfinance/simple.ijs'
eg: JHS IDE:edit '~addons/finance/finexec/basicfinance/simple.ijs'
Source Script Names 
Script names as general rule use lowercase. For example:~addons/finexec/basicfinance/simple.ijs
Script Status
Defined as: done: update: review: todo: dev: 

Definitions

Names 
The naming style for verbs, adverbs and conjuctions is to commence with a lower case letter 
and can be all lower case or camel case.
The naming style for nouns is to commence with an upper case letter and can be all upper case or camel case.
Documentation
Definitions start with NB.* and can have some or all of the following documentation details:
(Even for the most trivial or simple definitions.)
Name(type): type: (acvmdn) for/or adverb, conjunction, verb, monad, dyad, noun
Form: tacit or explicit 
Depend: If required list any dependent definitions even if from the stdlib and script. eg:  def/script
Description: What the definition is used for and if applicable an equation.
Note: Any special details.
Syntax: Details of how the definition is used and specification of the data inputs to the definition.
Left(L) and Right(R) arguments in the syntax to a definition have been enclosed in brackets eg:
     definition(R)
  (L)definition(R)
The brackets are generally redundant and are used for clarity. 
Example: The examples can be tested to review the performance of the definition.

Form of Definition : Tacit or Explict

Definitions have two forms, tacit or explicit. 
Tacit definitions have no dependencies and are self contained only using J primitives.
The adverb fix f. can be is used to create a fixed tacit.
A tacit definition can be defined and used in an explicit definition.
Explicit definitions are created with the verbs:
   3 : 0 or 4 : 0
The Form of a definition (tacit or explicit) can be useful in deciding how to to use it 
or modify it for a project or job.
The explicit form is generally easier to produce, read, debug and often useful for developing the tacit.  
The tacit form is produced as first choice if possible otherwise the explicit form is used.
Explicit definitions are generally stand-a-lone but may include dependencies.
Always check the documentation of the definition and source script.
A tacit definition may also have an explicit form: zzz and zzz_E.

Equations

Where possible equations are provided for definitions in a script.
Equations are in html files using the <math> HTML markup element.
The equations are created using the MathType application.
Some browsers may not support the <math> element and therefore equations will 
not be displayed correctly.

Updated: 2022-05-23