Author Topic: Changes to Comment Lines and Uncomment Lines  (Read 13864 times)

ScottW, VP of Dev

  • Senior Community Member
  • Posts: 1471
  • Hero Points: 64
Changes to Comment Lines and Uncomment Lines
« on: June 06, 2007, 06:34:47 pm »
We are working on some changes to Comment Lines and Uncomment Lines. We thought it would be great to solicit your feedback prior to releasing this work. Please read through this and respond if you think there is something critical missing. We believe this encompasses the most commonly used commenting styles. Thank you for your help.

--Scott

Specification

Commenting lines out of code is a common technique to temporarily remove the effect of a set of lines. It is considered a bad practice to leave lines commented out for long periods because the reason for them being removed is often lost and maintainers are left to wonder whether they should be added back in.

Commenting lines out is performed by selecting a contiguous set of lines and then invoking the Comment Lines operation. The selected lines may be at different indent levels. Some lines may already be commented out. It is very unusual for the selected lines to include the first or last line of a control structure, like if or for, without including the full control structure since that would typically produce a syntax error.

Code: [Select]
//         if (x > 10) {
//             line 1;
//             line 2;
            line 3;
        }
Figure 1, Partial comment of block

Invariants and heuristics
1.   Uncommenting lines should return the lines to their previously uncommented state. So, if you start with a set of lines, comment them out, then uncomment them, you should return the text to its initial condition.
2.   Placing the slashes at the left margin should not change the indent of the selected lines. This allows you to read the code and clearly see the indent level relative to lines that are not commented out. This may not hold if the user elects to comment out something at the outermost level.
3.   If we have to adjust the indent level of any line in the selection, then the entire selection should be indented the same amount, preserving the relative level of indentation for the selection. This should be true regardless of whether comment characters are placed at the left margin or at the current level of indent. This should also be true if you indent with tabs.
4.   Comment lines should work the same regardless of whether a line selection was chosen or a character selection is used.
 
Feature Set: Comment Lines
1.   For each line selected, prefix each line or surround each line with the characters specified on the Tools > Options > File Extension Setup, Comments tab for “Comment line”.
2.   Use the characters specified for Comment line literally. If the user enters two slashes and a space, then insert a space between the slashes and the first character of the line as needed.
3.   Provide an option that specifies where the left characters go:
o   Left margin—characters are placed flush against the left margin. Make this the default.
o   Current indent level—characters are placed at the current level of indent.
4.   Do not change the indent of the code being commented out unless there is not sufficient space to insert the comment line characters. If it is necessary to move the code over, move the entire selection over by the same amount to preserve the relative level of indent. By definition, it will always be necessary to shift the text if the user has selected “Current indent level” for the location of the left characters.
5.   If the source lines must be adjusted, be sure to adhere to user settings for spaces versus tabs when making the adjustment.
6.   If the user has specified right-hand characters on the Comments tab, align them vertically for all of the lines in the selection.
7.   If a user performs Comment Line on a line or lines that have already been commented out, add another set of comment characters to the selected lines. The characters should be nested so that you can clearly tell where lines were previously commented out.

Code: [Select]
       while (x > 10) {
           //line 1;
//         line 2;
           line 3;
       }

Figure 2, Repeated Commenting, Before

The following figure shows how the lines should appear if the comment characters are placed at the left margin. Notice how “line 1” is still commented out at the current indent level. Since this line was previously commented out, we want to preserve that when the newly inserted comment characters are removed by Uncomment Lines.
 
Code: [Select]
//        while (x > 10) {
//            //line 1;
////          line 2;
//            line 3;
//        }
Figure 3, Repeated Commenting, After

The following figure shows how the lines should appear if the comment characters are placed at the current indent level. Notice that the comment characters on “line 2” at the left margin are still in place.

Code: [Select]
       //while (x > 10) {
       //    //line 1;
//     //    line 2;
       //    line 3;
       //}

Figure 4, Repeated Commenting, After

The following figure shows the result if only the lines inside the while loop were commented out. Notice how the comment characters on “line 1” are doubled up since that line was already commented out before.
 
Code: [Select]
       while (x > 10) {
           ////line 1;
//         //line 2;
           //line 3;
       }

Figure 5, Repeated Commenting, After

Feature Set: Uncomment Lines
1.   Uncomment Lines removes the line comment characters from each line in the selection.
2.   The source lines may need to be adjusted when the characters are removed. To determine this, look for the appropriate indent level for the first line in the selection. If the line is not at that location, re-indent that line and apply the same amount of whitespace to the other lines in the selection.
3.   If the source lines must be adjusted, be sure to adhere to user settings for spaces versus tabs when making the adjustment.
4.   Uncomment Lines checks for well-formed comments before making any changes. A well-formed comment contains suitable line comment characters in the same column of every line in the selection.
5.   Use the set of line comment characters specified in the lexer for this language rather than just the characters specified on the Comment Tab. A user may be uncommenting lines that were commented out by someone else. This feature should still work if they are using legal characters and the comments are well formed.
6.   When this feature detects that this is not a well-formed comment, it should abort the operation with the message, “Cannot remove comment characters. Unrecognized or inconsistent commenting approach has been found.”
7.   Uncomment Lines may be applied to nested line comments (see Feature 7 in Comment Lines). If so, it should remove the characters in such a way that if Comment Lines were applied to the result, it would return the selected lines to their previous state. For characters placed at the left margin, this may entail shifting the nested comment characters to the left while leaving the source code in the same column. This can be accomplished by deleting the innermost set of comment characters in most cases.


grbroderick

  • Community Member
  • Posts: 9
  • Hero Points: 0
Re: Changes to Comment Lines and Uncomment Lines
« Reply #1 on: June 07, 2007, 03:38:19 pm »
How about doing something similar to what you're doing with curly braces, when a multi-line comment is started?

In other words, the user types:

/*

which slickedit completes with

*/

on the next line, displays a horizontal line in the editor window and allows the user to use the up-arrow and down-arrow keys to surround / un-surround lines of code or text that they wish to be enclosed within comments?

alex

  • Community Member
  • Posts: 64
  • Hero Points: 6
Re: Changes to Comment Lines and Uncomment Lines
« Reply #2 on: June 07, 2007, 05:48:48 pm »
Off-topic: I see there's a way to do this via the menus, but how can I bind this to a key?  I can't find the commands that implement this functionality.

Sandra

  • SlickEdit Team Member
  • Senior Community Member
  • *
  • Posts: 754
  • Hero Points: 36
Re: Changes to Comment Lines and Uncomment Lines
« Reply #3 on: June 07, 2007, 06:17:05 pm »
Off-topic: I see there's a way to do this via the menus, but how can I bind this to a key?  I can't find the commands that implement this functionality.

The command for Comment Lines is "comment" and for Uncomment Lines is "comment-erase".  You can access this functionality via the command line with the same commands or bind keys to them using the keybindings dialog under Tools > Options > Key Bindings.

Lisa

  • Senior Community Member
  • Posts: 238
  • Hero Points: 24
  • User-friendly geek-speak translator extraordinaire
Re: Changes to Comment Lines and Uncomment Lines
« Reply #4 on: June 07, 2007, 06:53:10 pm »
Off-topic: I see there's a way to do this via the menus, but how can I bind this to a key?  I can't find the commands that implement this functionality.

Sandra answered your question, but here is some additional information you might find useful. You can also find this information in the Help. Go to Help > Contents, and on the Contents tab, navigate to Menus, Dialogs, and Tool Windows > Document > Document Menu -- you will see a table that lists the items on the Document menu and their corresponding commands. We have a table in that chapter for every main menu item.

Also, if you go to the Help > Index and type in "comments" and go to that topic, we have a whole section about the topic, with descriptions of the commenting menu items and their associated commands.

jbhurst

  • Senior Community Member
  • Posts: 405
  • Hero Points: 33
Re: Changes to Comment Lines and Uncomment Lines
« Reply #5 on: June 07, 2007, 10:57:29 pm »
Hi,

I think it's great that this area is getting some work, and it sounds like you are being pretty thorough in your analysis. The current commands are OK in concept, but they have a few glitches and are easily confused.

FWIW, my usage style of the current commands is like this: I have two macros of my own:
Code: [Select]
boolean in_comment(); // detects whether cursor is currently on a commented line
_command void toggle_comment(); // calls comment_erase/comment according to whether currently in comment

The toggle_comment command also moves the cursor to the next line if there is no selection. With toggle_comment bound to a key one can toggle the comments on or off lines quickly both with and without a selection. The scheme is modeled on the comment toggling in IntelliJ IDEA.

It works pretty well, but occasionally falters when SlickEdit's comment/comment_erase get confused.

Regards

John Hurst
Wellington, New Zealand

hs2

  • Senior Community Member
  • Posts: 2752
  • Hero Points: 291
Re: Changes to Comment Lines and Uncomment Lines
« Reply #6 on: June 08, 2007, 10:39:17 am »
I agree with John. (My 'toggle_comment' command behaves almost the same except the cursor movement.)
IMO the spec. seems to be complete and only the 'no active selection' case is missing and a 'toggle_comment' command.
If no line is selected I'd propose that just the current line is taken with an option to move the cursor to the next line.
A 'toggle_comment' command is very useful and covers at least 90% of all use cases.
The first / curr. line should be considered to comment or un-comment the selection / curr. line.
This is easy to understand and is only not applicable if the 1st line of a selection to comment is already commented.
A pop-up simliar to the 'delete-line'/'delete-code-block' could be a smart solution even for this case.

Edit: Another solution coud be to check the whole selected block (of lines) for at least 1 line which is not yet commented to select the 'comment' mode.

HS2
« Last Edit: June 08, 2007, 12:02:38 pm by hs2 »

TxDot

  • Community Member
  • Posts: 38
  • Hero Points: 0
Re: Changes to Comment Lines and Uncomment Lines
« Reply #7 on: June 08, 2007, 11:49:35 am »
I think an option to include some default text on the first comment line would be handy. The text should support variables such as logon id, date, time, etc. Another option to pop up a text box for the user to add their own comments would be nice. Many shops use a trouble ticket model where the trouble ticket number is inserted in the code as a reference point. The popup would be an ideal time to enter the trouble ticket number. Maybe a blank comment line should be inserted to hold this text if the user selects the option. Here is an example;

// Following lines commented out by joeblow on 2007-06-08-06:46 QM00123456
// blah
// blah
// Previous lines commented out by joeblow on 2007-06-08-06:46 QM00123456

hs2

  • Senior Community Member
  • Posts: 2752
  • Hero Points: 291
Re: Changes to Comment Lines and Uncomment Lines
« Reply #8 on: June 08, 2007, 12:26:30 pm »
I think there are 2 problems with that feature.
1. What should happen if the user wants to uncomment a block ? It's not possible (at least there is no easy way) for SE to determine that it has to delete the additional lead-in[/out] comment lines.
2. Every line comment is surrounded by this additional text. But this is up the user so it's not a real probem.

I'm using the 'alias' facility for my TODOs and comment block comments. It already provides a lot of features for that purpose. You could use it quite easily write your own 'ticket-comment' command incl. the alias expansion if you want to avoid the extra steps of expanding your e.g. tb (ticket-begin)/ te (ticket-end) aliases manually.

HS2

alex

  • Community Member
  • Posts: 64
  • Hero Points: 6
Re: Changes to Comment Lines and Uncomment Lines
« Reply #9 on: June 08, 2007, 04:01:49 pm »
Off-topic: I see there's a way to do this via the menus, but how can I bind this to a key?  I can't find the commands that implement this functionality.

Sandra answered your question, but here is some additional information you might find useful. You can also find this information in the Help. Go to Help > Contents, and on the Contents tab, navigate to Menus, Dialogs, and Tool Windows > Document > Document Menu -- you will see a table that lists the items on the Document menu and their corresponding commands. We have a table in that chapter for every main menu item.

Also, if you go to the Help > Index and type in "comments" and go to that topic, we have a whole section about the topic, with descriptions of the commenting menu items and their associated commands.

Thanks, I didn't know about that help section that lists commands for menu items.  That's super-useful!  I tried looking at the menu definition via Macro|Menus, but I couldn't find the document menu.  (That would be a nice thing to be able to do.)

I did try searching for comments in help, but I guess I didn't look hard enough :)

Lisa

  • Senior Community Member
  • Posts: 238
  • Hero Points: 24
  • User-friendly geek-speak translator extraordinaire
Re: Changes to Comment Lines and Uncomment Lines
« Reply #10 on: June 08, 2007, 04:13:03 pm »
Thanks, I didn't know about that help section that lists commands for menu items.  That's super-useful!  I tried looking at the menu definition via Macro|Menus, but I couldn't find the document menu.  (That would be a nice thing to be able to do.)

I did try searching for comments in help, but I guess I didn't look hard enough :)

Ah! That reminds me - I think you could have found it through Macro > Menus (you probably wouldn't have known what to look for - we do need to document this). Go to Macro > Menus, and on the Open Menu dialog, select _mdi_menu and click Open. The Menu Editor opens and you can see a list of all the main menu items. Double-click the Plus icon to expand "Do&cument" - you will then see all the menu items under Document and the associated commands. I use this a lot when I'm trying to find the same information myself - I can't believe I forgot to point it out...may be useful to others so thanks for the reminder! :)

dunkers

  • Senior Community Member
  • Posts: 738
  • Hero Points: 33
Re: Changes to Comment Lines and Uncomment Lines
« Reply #11 on: June 08, 2007, 05:46:13 pm »
How about doing something similar to what you're doing with curly braces, when a multi-line comment is started?
Yes, I'd like this one as well.

Edit: I'd like this to happen also when entering "#if ..." and similar. I know of the 'surround with' facility but that requires pre-selecting the lines.
« Last Edit: June 08, 2007, 05:50:17 pm by dunkers »

TxDot

  • Community Member
  • Posts: 38
  • Hero Points: 0
Re: Changes to Comment Lines and Uncomment Lines
« Reply #12 on: June 08, 2007, 09:23:58 pm »
How about doing something similar to what you're doing with curly braces, when a multi-line comment is started?
Yes, I'd like this one as well.

Edit: I'd like this to happen also when entering "#if ..." and similar. I know of the 'surround with' facility but that requires pre-selecting the lines.
I also would this since I usually #if 0 ... #endif lines of code instead of commenting them out.

TxDot

  • Community Member
  • Posts: 38
  • Hero Points: 0
Re: Changes to Comment Lines and Uncomment Lines
« Reply #13 on: June 08, 2007, 09:25:32 pm »
I think there are 2 problems with that feature.
1. What should happen if the user wants to uncomment a block ? It's not possible (at least there is no easy way) for SE to determine that it has to delete the additional lead-in[/out] comment lines.
2. Every line comment is surrounded by this additional text. But this is up the user so it's not a real probem.

I'm using the 'alias' facility for my TODOs and comment block comments. It already provides a lot of features for that purpose. You could use it quite easily write your own 'ticket-comment' command incl. the alias expansion if you want to avoid the extra steps of expanding your e.g. tb (ticket-begin)/ te (ticket-end) aliases manually.

HS2
That's why this should all be user controlled. Sometimes I would want it and sometimes I wouldn't.

AllenR

  • Community Member
  • Posts: 11
  • Hero Points: 0
Re: Changes to Comment Lines and Uncomment Lines
« Reply #14 on: June 11, 2007, 06:53:08 pm »
Scott, does Feature Set item 3 include the "Start in Column" from the Comments tab of the Extension Options?  COBOL may be only language that is column specific for comments (col. 7).  ASM390 should fall into the left margin setting.

How do right margin / truncation settings fit in here?  Would you shift code outside margin / truncation column?

Thanks, Allen.