Lesson 15: Commenting Your Code
It is generally a good idea to comment your code. Comments will make it much easier to remember what's going on, can help you locate bugs, and also be of significant benefit to others who may work on your code at a later time.
Toka provides two ways to comment your code.
Single Line and Block Comments
At the listener (the top level interpreter), you can use #! to create single line or block comments. These are comments that start with #! and end at the end of the current line. For example, I often start my programs with a short information block such as the following:
#! --------------------------------------------------------------- #! A small HTTP server for Toka #! #! Developed by: #! Charles R. Childers #! erider #! #! ---------------------------------------------------------------
This style comment works well for blocks, and thus can be very useful at the start of a function:
#! --------------------------------------------------------------- #! get-request #! This reads a client request of up to 1k into the buffer. The #! number of bytes read is returned. #! ---------------------------------------------------------------
#! comments can not be used inside quotes. Inside Quotes
Inside a quote, you can use ( ... ) comments. These start with a ( and end when ) is encountered. Unlike #! comments, these can span multiple lines and be used inside of quotes. An example:
[
connection ( -a )
@ ( a-n )
pClose ( n- )
] is end-connection
In this example, each stack action is mapped out using a stack comment. This is helpful when learning to use Toka, as it makes it easier to visualize the stack at each step.