objectionary
mandatory comments for all abstract objects
Let's add a new XSL check into eo-parser that will verify whether all abstract objects have comments prepending them. The severity level should be warning.
Also, let's make sure the comment:
- starts with a capital letter
- ends with a dot
- includes only ASCII printable characters (
0x20-0x7f) - is at least 64 characters long
- is in Markdown
- is grammatically correct :)
@yegor256 we don't save comments into XMIR, so we can't check their presence through XSL.
- Do we really need it? Because anonymous abstract object can be used as arguments of application
while.
TRUE
# Comment here
[i]
i > @
As for me, comment looks a bit strange here
2. We can extend comment rule in our grammar, but ANTLR will allow us to check only:
- starts with a capital letter
- ends with a dot
- includes only ASCII printable characters (but I'm not sure)
WDYT?
@maxonfjvipon maybe we can prohibit comments for anonymous formations ([x y z]) and make them mandatory for named formations ([x y z] > t)?
@yegor256
maybe we can prohibit comments for anonymous formations ([x y z]) and make them mandatory for named formations ([x y z] > t)?
So even if named abstract object is used as argument for application - it must have comment?
while.
TRUE
# Mandatory comment here
[i] > body
...
while.
TRUE
[i] # <-- no comment here
...
@yegor256
can we check that each comment is a valid Markdown?
I'm afraid we can't do it while parsing itself. But I think we can do it while listening in XeEoListener. There we can also check the length of the comment, printable characters
@yegor256 what about horizontal abstract object that may contain inner horizontal abstract objects?
# Mandatory comment
[] ([] (a > b) > y) > x # <--- can't place mandatory comment if front of y
It's the same as:
# Mandatory comment
[] > x
# Mandatory comment
[] > y
a > b
@yegor256 I think we should not check the length of the comment before abstract object. Why:
- Object may have a complex logic and explanation of its work may take many words and symbols, for example
cage - We won't be able to leave todos in EO code
- We won't be able to "inlined EO inserts" in the comment in order to show how the object works (in far future)
So I suggest not to check the length of the comment at all. WDYT?
@maxonfjvipon you mean, we should not require the comments to have at least 64 symbols, as originally suggested?
@yegor256 maybe reduce this rule to "at least 32 chars"? 64 seems to be quite many
@maxonfjvipon it's better to start with as strict requirement as we can. If we start with 32, it will be impossible to make it larger later, since many programs will be written already.
