q Language Programming Style Guidelines

This document contains the standard conventions that we follow and recommend that others follow. It is very heavily based on the K: Remarks on Style - No Stinking Loops updated to be based on q. It covers indentation, comments, declarations, statements, white space, naming conventions, programming practices and includes examples. (source)

  • 80% of the lifetime cost of a piece of software goes to maintenance.
  • Hardly any software is maintained for its whole life by the original author.
  • Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.

Where possible q idiomatic syntax should be used, take advantage of the power q provides. i.e. Use adverbs where possible rather than loops. Use inline functions with implicit parameters, Use q's right-to-left evaluation to use as few brackets as possible but not at the cost of clarity. e.g.


Contents

  1. Typical File Layout and Contexts
  2. Naming Conventions
  3. Comments
  4. Braces / Spacing
  5. Functions
  6. Miscellaneous
    1. Projections
  7. breaking on exceptional client calls

Example logger.q

Typical File Layout and Contexts

Typically for libraries intended for use by others:

  1. All functions will be declared within one file with the suffix .q
  2. All contents within that file will be declared within one context, the context will be the same as the filename.

Naming Conventions

Overall Naming Rules

  • Use camelCasing
  • Avoid underscores _ since this is also a kdb operator.
  • Avoid periods "." as these are used for contexts.
  • Avoid reserved words and spaces for column names.
  • Variables x,y,z should only be used for default function arguments to prevent confusion.
Scope Entity Convention Example
Contexts Short camelcase starting with lowercase. .ts
Global Variables Begin with uppercase letter. Counter
Constants All upper-case REUTERSID
Functions Begin with lowercase letter. verbNoun pairs executeTrade
Local Functions Begin with lowercase letter. verbNoun pairs executeTrade
Variables Begin with lowercase letter. Very limited scope use single letters otherwise longer nouns. a, b, messageCount, corruptMessages

Comments

Comments should follow the qDoc format where possible, allowing generation of html documentation.

  1. At-least document:
    1. The file and its purpose at the top.
    2. Every public entity / function that is allowed to be referenced by an external party, it's parameters and returns.
  2. Avoid the / on a line by itself, too often people forget to close it.
  3. Use // or / at end of line freely

Braces / Spacing

  1. Use a new line for each separate stement.
  2. Use a level of tab nesting for each statement block and control sequence.

e.g.

Functions

  1. A function should be no more than 20 lines, at which point it should be examined for refactoring and/or broken up into sub-functions.
  2. Always place a semi-colon after a function definition. (this allows running in qStudio / kdb Studio)
  3. The only assignments that do not require a line by themselves are those where the value is only used within the line itself.
  4. Name parameters as often as possible

Misc

Projections

Never elide semicolons projections, always make explicitly clear it is a projection. e.g.

f[;2;] / rather than f[;2]

See Also