Commenting Procedures


#1

What is a best practice for comments in a procedure?


#2

Best practice, and what I actually do may not be the same thing. The programming books generally show one big comment at the beginning of the procedure that explains what the procedure is doing, and where it expects to get the information it needs to do its work, generally which parameters will contain what information, and how they will be formatted, if it’s a subroutine.

Then, smaller comments will be interspersed with the code, to mark where the start of different sections of the code begin, or to point out anything unusual about a statement. If you are doing something tricky, you might not get the idea 6 months later, without a reminder.

Dave


#3

Thank you @dave , so in adding the comment, either as you describe or scattered through out the code, is the format for Panorama X /* some comment */ or // and the comment. I seem to recall an issue with some of the ways comments were formatted and where they were inserted. I need to add comments and I don’t want to cause any issues with my database.


#4

Both will work. For a large comment that spans several lines, I think it’s easiest to use the /* … */ form because it can span several lines. The issue, as I recall, was nesting comments like /* … /* … */ … */. Panorama 6 supports nesting but I think there may be an issue with that in Panorama X.

Dave


#5

For a single line I will use // but for multiple lines I will write the comment and then select the entire block and hit command-/. I also use this method to temporarily comment out sections of code. Once I need to reactivate it I select it all once again and hit command-/ to return it back to normal code.


#6

As already written here, either // or /* */ is fine, Panorama accepts both.

// This is a single line comment
message "hello" // the end of this line is a comment

/*
   this type of comment
   can be multiple lines
/*

You can also often use /* */ in the middle of a line. If you do that, it has to go in a spot where whitespace is allowed (so you can’t, for example, put it in the middle of a variable name).

message x /* balance */ - debit

Of course in this case you’d be much better off creating a variable called balance!

As Dave mentioned, Panorama X does not support nesting of /* */ comments, as illustrated here:

/*
    this is a comment
    /* this is still a comment */
    this portion is a comment in Panorama 6 but not X
*/

This may change eventually but it is pretty low priority – most programming languages that support /**/


#7

By the way, the Help system has a page that discusses comments:

Ooops – I see a mistake – it says that /* */ comments can be nested.


#8

All this talk about comment delimiters leaves out “;”. I have used that extensively (the same way // is used) in Pan 6, is it still going to work reliably in Pan X?


#9

See the help page Jim gives above. The last line of this page states:

You can also temporarily remove a single line of code by putting // at the beginning of the line (or ;).

Ok, two things here. First is that this does not have to be at the beginning of the line of code but can be anywhere in the line and everything following on that line will be a comment. Second, I noticed that using the “;” does not highlight the comment. If I replace this with the // for the comment it is highlighted.


#10

Also the first paragraph says:

Panorama has three different comment styles: /* … */, //, and ;.

However, as Gary mentioned, syntax coloring doesn’t work for semicolon comments, so the comment text appears black. But they still act as a comment.