"Sputnik" help  
Sputnik Help
Language Reference - Datatypes - Comments
In Sputnik there are two types of comment you can use to add information to your code so you can read it later and understand how stuff works better.

The most common comment people use is the // comment this comment originates from C and is fairly easy to type.

You use a // comment like so:

// The comment goes here
say "hello"; // it can also go here

The // comment can be used after a statement or by itself in a single line you can't place code after the // since it will be ignored (if on same line that is).

That brings us to the final comment type the /* */ comment found in C it is rarely used unless you require a multiline comment you use it like so:

/* The comment goes here */
say "hello"; /* it can also go here */
say /*oh it can go here too*/ "hello";

You will notice it comments out everything from /* to */ and it will use the first */ it finds to end the comment.

One benefit of this is you can place it inside statements as shown above.

Finally an example of using /* */ as a multiline comment:

/* Comment
   Goes
   Here
*/

// OR

/* 
   Comment
   Goes
   Here
*/

// Some prefer...

/* Comment
 * Goes
 * Here
 */

Sputnik supports nested /* */ multiline comments:

/* Comment
   Goes
   /*
   hello
   */
   Here
*/

The ability to use nested /* */ comments in Sputnik is a distinctive feature. While it's a powerful tool for providing detailed explanations within code, developers should exercise caution to avoid potential complications that can arise from nested comments. While not commonly found in many programming languages, Sputnik's support for nested comments adds flexibility for those who require this level of commenting granularity. However, it's essential for developers to use this feature judiciously to maintain code readability and avoid unintended consequences.

It is not recommended to do nested /* */ comments since it can easily break things if you get careless with it however Sputnik supports it assuming you can remember where you put them all. However it is possible to do so and will remain that way in Sputnik.

Sputnik supports one final comment you start it with #begin and stop it with #cut it comes from the preprocessor Begin, Cut directives.

#begin hehe
    say "hello";
#cut

You can also name these comments:

#begin a name goes here
    say "hello";
#cut

Setting the editor to allow them collapsing is useful too.

Sputnik supports documentation pods using #pod and stop it with #cut it comes from the preprocessor Pod, Cut directives.

#pod
          So we can place documentation here
          and it will not gain syntax highlight
          useful for when somebody wants to read the comment
          but not have it looking like comment colors
          helps it stand out more for documentation
#cut

Pods can also be named:

#pod Copyright Notice -- App Testy Maximus
          So we can place documentation here
          and it will not gain syntax highlight
          useful for when somebody wants to read the comment
          but not have it looking like comment colors
          helps it stand out more for documentation
#cut

While technically this is a comment its designed to not "look" like a comment so the text does not go comment color. The purpose of this is to create documentation its intended that the user can read it very clearly.

A #pod and #cut combination in Sputnik serves as a special markup for creating documentation pods within the code. The purpose of this feature is to allow developers to embed clear and detailed explanations directly in the source code without these explanations being visually treated as regular comments. By using #pod at the beginning and #cut at the end, the enclosed text remains distinct from the main code and is not colored as typical comments. This ensures that the documentation is easily visible and readable, enhancing its clarity for developers who may need to understand the codebase. This approach helps in maintaining well-structured, easily accessible, and visually unambiguous documentation within the source code.

It is worth noting you cannot use # as a stand alone comment since # is used by the Preprocessor much the same way as it is in C.

That is all the comment types found in Sputnik.


Contact
Cheryl (uberfox@hotmail.com)
Homepage
http://ubersoft.org