Comments¶
Comment every line of a q function, keeping code and comment on the same line.
Align the comments for ease of reading.
Indent the comment block to mirror that of the function.
sendLeft:{ / update from left to right links at x=_i
s:get[_v;`G] / absolute source field name
h:(::;*:)?get[_v;`H] / 0 (::) or 1 (*:)
j:enlist@x / itemwise index
p:.[att[_d;`J];undot s] / left link partition
i::[h;p j;p . x] / index map into right table
d::[h;_v j;_v . x] / first (*:) or all (::)
@[s;i;:d] / update source field
}
A function in an early version of k: the comments now even more valuable than before
Conventions for comments¶
line | comment |
---|---|
Local assignment | Describe the meaning or the role of the variable. |
Side effect | Use the imperative mode, indicating the action performed. |
Control structure | Describe the meaning of the condition or loop. |
Document ‘dangerous curves’ in ALL CAPS, or use some other eye-catching device.
Header comments¶
How to comment the header of a q function is a matter of some controversy.
We recommend treating the header as just another line in the function, with this one difference: the comment should describe the meaning of the function as a whole.
Some programmers believe the header comment should contain standardized information about the function as a whole.
sendLeft:{
/ ds: update from left to right link
/ ts: sjt 2017.08.13
/ x: +i or _n if _i is ()
/ rs: none
/ gr: _v
:
The header comment block contains a function description, author and timestamp data, argument and result documentation, and information about which global variables are read and set. Unfortunately, this style tends to bloat functions with non-executable lines. Recall that the typical q function contains but five lines.
Help dictionary¶
The same information could be packed into a help dictionary for the function.
\d .sendLefth
ds:"update from left to right link"
ts:"sjt 2017.08.13"
x:"+i or _n if _i is ()"
rs:"none"
gr:"_v"
Any q variable (and functions are just variables) can have a help dictionary, which then can be displayed or inspected. This is consistent with q’s general approach to the constructs of programming: if it matters, make it first-class. (Eventually this form of help could be directly supported by q’s interactive debugger.)