Creating Multiline Comments

Since J allows programmers to create dense powerful code, multiline comments are useful for documentation. J provides two ways to create multiline comments.

The first is ‘NB.’ which creates multiple single line comments. It works like this – when the ‘NB.’ primitive is encountered, everything between it and the line feed to its right is ignored. Simply, anything right of ‘NB.’ is a comment, and everything to the left of ‘NB.’ is executed as regular J code.  ‘NB.’ can also comment out lines of code. Just insert ‘NB.’ at the beginning of the line. The J menus allow easy ways to insert or remove NB. quickly. The column of ‘NB.’s’ down the left column can look a little clunky, but otherwise it is a very powerful documentation tool. Summing up, ‘NB.’ is a primitive that causes J to ignore the line to its right, allows inline commenting, and is supported by menu shortcuts.

NB. Anything you want to type
NB. Can be added as long as it starts with NB.
2+3 NB. this part is ignored while 2+3 is processed
      5

A second option is the defined verb ‘Note’. which can take either right and left arguments, or just a right argument. The two argument (dyadic) form functions much like ‘NB.’ ignoring everything to its right until the next linefeed. The one argument (monadic) form allows true multiline comments. The single argument  is ignored, and subsequent lines become the comment, ending with a single ‘)’. ‘Note’ does have some constraints. First, as a verb, it requires noun arguments. Often, the right hand argument is a text string used as an identifier. So ‘Note’ cannot comment out code, since it interprets any verbs that are to its right, unlike ‘NB.’ which simply ignores them. Second, ‘Note’ cannot be embedded within another multiline definition, because all multiline definitions terminate with a single right parenthesis. So ‘Note’ would terminate the definition containing it. The positives? Well, ‘Note’ does look better, is truly a multiline comment and can enclose any J scripts simply by preceding with Note ” and following with a single ).

2 + 3 Note 'both arguments must be nouns, then the left side value is returned'
   5
Note 'Monadic form - this argument must also be a noun'
then each line
is part of the comment
until the last parenthesis.
)

‘NB.’ or ‘Note’ are subject to the writer’s ability to communicate with the audience. Too much information and the code feels bloated; too little and the reader may find the code opaque. It is a good rule of thumb to comment just enough to enable understanding. With all forms of communication having an accurate sense of the audience is vital.

A video tutorial follows (responses welcome):

Advertisements

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s