Naming conventions

Joshua Shinavier edited this page May 22, 2011 · 11 revisions

The following is a set of guidelines for the naming of Ripple programs and primitive functions. These are not strict rules; you can name your constructions whatever you like, as long as the names are syntactically valid. However, following these suggestions more often than not promotes a consistent look and feel in the Ripple environment.

Primitives

The names of primitive mappings (i.e. pre-loaded library constructs such as sqrt, map, each, etc. which can be referenced as keywords in Ripple queries) should:

  • use lowercase letters and hyphen notation, as in Lisp. For example, percent-encoded is preferred over percentEncoded, although both are legal. This scheme works well in Ripple, which has no infix operators with which to confuse the hyphen.
  • have a "declarative" flavor if possible, rather than a procedural one. For example inverse is better than invert, and percent-encoded is better than percent-encode. Imagine that you are traversing a graph of nodes and relationships, with functions as street names to guide you in the right direction (as opposed to baking a cake, where the recipe tells you what to do). Stack-shuffling primitives such as dup, swap, rotate, etc. (see the stack library) are a notable exception to this rule.
  • be consistent with other primitives in the same library. For example, if the sum of two numbers is called plus, then the difference should be called minus. If the sum is called add, then the difference should be called subtract or sub.

User-defined names

The @lists or programs you define at the command line are very similar to primitives: they're filters which consume a stream of stacks and produce another stream of stacks. As such, they follow similar naming conventions. Particularly useful user-defined lists may even go on to be implemented as primitives.