Design #481
Multiline comments -- obsolescent?
Description
Multiline comments are convenient, inconvenient and potentially hazardous.
Convenient for commenting out blocks of code quickly.
Inconvenient for the emacs UI (and probably the GUI too).
Potentially hazardous since C5 does not recognise nested /*...*/
JAA proposes "discouraging" multiline comments:
(a) eliminate the /*...*/ syntax
(b) forbid multiline /*...*/ comments (but single line OK)
(c) allow multiline /*...*/ but with a warning
(d) allow them but put a warning in the doc.
Related issues
History
#1
Updated by John Abbott about 10 years ago
Updated by - Status changed from New to In Progress
- % Done changed from 0 to 10
My opinion is:
(a) is too drastic: not backward compatible, single line /*...*/ can be useful
(b) my favourite (and I believe it is the right solution)
(c) possibly useful stepping stone towards (b), sort of backward compatible
(d) backward compatible (but no other positive features)
The convenience of multiline /*...*/ comes from being able to comment out blocks of code; this could be replaced by ensuring that the UIs have a "comment out block" operation which puts an end-of-line comment at the start of each line in the block. Note that this approach also avoids the potential hazard of unrecognised nested comments.
NOTE emacs UI already has a comment-region command; no idea about the GUI.
#2
Updated by Anna Maria Bigatti about 10 years ago
Updated by - Target version set to CoCoA-5.1.0 Easter14
Current cvs produces a "warning". That's very good for maintainers who have to deal cleanly with lots of code.
For users, with muche simpler files, probably with outputs commented out with /* */, and who are less likely to produce lots of trouble with multiline comments I believe we should leave this possibility (even C++ allows it).
So I suggest, as for many istances of this kind, to set this at the same warning-level as the warning for compulsory ";" .
I think we should to that until we can offer the "comment-region" facility in the GUI
as we offer in the EmacsUI.
#3
Updated by John Abbott about 10 years ago
- % Done changed from 10 to 20
I have changed the warning level to WS_PEDANTIC, so most users won't see the warnings.
[now I have to change my settings so that I do see the warnings -- is there a C5 function to change the level of warnings that actually appear?]
#4
Updated by John Abbott about 10 years ago
- Status changed from In Progress to Resolved
- % Done changed from 20 to 70
I think this issue is resolved now -- any objections?
The solution is (c): multiline /*...*/ allowed but issues a "pedantic" warning.
Note that I have also added a warning when /* is found inside a /*...*/; this should avoid nasty surprises arising from nested comments (and hopefully not trigger too many false positives).
#5
Updated by Anna Maria Bigatti about 10 years ago
John Abbott wrote:
I have changed the warning level to
WS_PEDANTIC, so most users won't see the warnings.
I think that's good (at least until we can fix the GUI...)
[now I have to change my settings so that I do see the warnings -- is there a C5 function to change the level of warnings that actually appear?]
No, I don't think so. Should I add it to VersionInfo?
To change your setting in emacs go to the CoCoA menu and click on Preferences.
Now I see that I have to make the explanations more verbose, otherwise they get unnoticed (even by me!)
#6
Updated by Anna Maria Bigatti about 10 years ago
John Abbott wrote:
Note that I have also added a warning when
/*is found inside a/*...*/; this should avoid nasty surprises arising from nested comments (and hopefully not trigger too many false positives).
Good, that should warn when commenting out a matrix with the ring description. BTW For rings with unique implementation (ZZ, QQ, RingQQt(n)) now it prints the ring with no comment symbol.
#7
Updated by John Abbott about 10 years ago
- Status changed from Resolved to Feedback
- Assignee set to John Abbott
- % Done changed from 70 to 90
- Estimated time set to 4.00 h
The solution chosen is (c)
#8
Updated by John Abbott almost 10 years ago
- Status changed from Feedback to Closed
- % Done changed from 90 to 100
Current approach is satisfactory (& even fairly backward compatible if you don't nest /*...*/ style comments)
Closing.