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.

1 2.2 3 / real vector (1;2.2;3) / list of integers and reals

Example logger.q

/ ######################### logging to disk/table/console / a logger based on java's, including handlers,filters,formatters. But note there is only one gloal logger. / handlers - are notified when a logging event occurs / formatters - convert a logrecord into a string / filters - restrict what messages are actually logged / . / example: .logger.info["myClass";"err txt message"] system "d .logger"; EventCount:0; / global counter of events occurred since load DATEFORMAT:"yyyy-mm-dd"; / format for writing dates to log file / Log an event / @param level - a logger.levels symbol, in order (higher priority first) `SEVERE`WARNING`INFO`CONFIG`FINE`FINER`FINEST / @param message - the message to log loqEvent:{ [level;message] logRecord:(`level`class`message)!(level;class;message); EventCount+:1; // pass the logRecord to all handlers (til count handlers) handlers \:logRecord; }; /### change any arg passed in, into a string frmt:{$[10=abs type x; x; @[{""{x,"\n",y}/.h.td x}; x; "\r\n",.Q.s x]]}; system "d .";

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.

calculateInterest:{ [rate; periods] if[periods > 10; r:useMethodA[rate;periods*12]; recordValue[rate;r];]; recordRate[rate]};

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]