In-language commenting
Lua is clever and uses --[[ ... --]] for multi-line comments. The usefulness in this scheme is that the syntax used for closing a multi-line comment IS a comment, and no syntax error results if you comment out the opener by adding an extra -, which re-enables the commented out section. The part that I don't like is how single-line comments are specified, with --. Just IMO, FWIW, etc., I don't think the same characters used for basic operators should be re-used for something like a comment. Really, shouldn't a = a -- 2 result in a-4?
The same in C99/C++, how does using // to specify a comment really make sense? a //= 2 ? a ///= 2 ? /* */ -style comments are better, I suppose, because they are an obvious nop.
Ideally I think we would be using something that allows for the abuse that Lua's multi-line comments gives us, without overloading any of the basic operators provided by the language. `` perhaps?
`` Comment
``
Multi-line comment
``
`` ``
`` Active multi-line comment?
a //= 37;
``
Maybe, I'm not sure.
There are also languages that allow comments to effectively serve as documentation that is preserved (potentially) at runtime. For example, Python assumes unassigned strings immediately inside a class or function definition are to serve as a documentation block for that section. These documentation blocks can be accessed through runtime introspection, or used with appropriate tooling to generate documentation. This is a great approach from my experience, and perhaps -all- comments should be given the opportunity (optionally) to persist alongside the code for which they are intended.
If one is to take this approach, how does one rectify comment specification with static string initialization? Especially with regards to whitespace (esp. newline) handling? How does one specify to what block of code a comment refers when not at the beginning of a closure of some sort? Is there even any point in preserving these comments for any sort of runtime introspection or should the goal be simply the production of documentation, ala Literate Programming?
The same in C99/C++, how does using // to specify a comment really make sense? a //= 2 ? a ///= 2 ? /* */ -style comments are better, I suppose, because they are an obvious nop.
Ideally I think we would be using something that allows for the abuse that Lua's multi-line comments gives us, without overloading any of the basic operators provided by the language. `` perhaps?
`` Comment
``
Multi-line comment
``
`` ``
`` Active multi-line comment?
a //= 37;
``
Maybe, I'm not sure.
There are also languages that allow comments to effectively serve as documentation that is preserved (potentially) at runtime. For example, Python assumes unassigned strings immediately inside a class or function definition are to serve as a documentation block for that section. These documentation blocks can be accessed through runtime introspection, or used with appropriate tooling to generate documentation. This is a great approach from my experience, and perhaps -all- comments should be given the opportunity (optionally) to persist alongside the code for which they are intended.
If one is to take this approach, how does one rectify comment specification with static string initialization? Especially with regards to whitespace (esp. newline) handling? How does one specify to what block of code a comment refers when not at the beginning of a closure of some sort? Is there even any point in preserving these comments for any sort of runtime introspection or should the goal be simply the production of documentation, ala Literate Programming?