Repository navigation
Use of abbreviations and jargon #52
Description
I assume that the use of abbreviating statement as stmt is for CPython compatibility. Another reason might be that it's slightly less to type but I think that's no longer a big concern, now that we have powerful IDEs like rust-analyzer.
The downside I see with using abbreviations (and chargon) is that it increases the barrier for new contributors for RustPython or downstream crates. Some of them may never have heard of stmt or what an expr is and it takes them, maybe only a little, time to understand that it is an abbreviation for statement.
That's why we at rome had the following two philosophies when it comes to naming:
- Utilize verbosity when naming commands and flags. No unnecessary and confusing abbreviations.
- Reduce jargon. Don’t assume that users will understand specific terminology. Strive to provide clear meaning for experts and beginners. For example, use “character” where you would traditionally use “token” when producing parser errors.
I'm curious to hear your perspective on this subject.
Activity
[-]Avoid abbreviations[/-][+]Use of abbreviations and jargon[/+]youknowone commentedon May 17, 2023
In my opinion, the biggest benefit of using the Python(not CPython, but Python here) AST originated terms is documentation. People can learn it from official document https://docs.python.org/3/library/ast.html
Another benefit is matching with python runtime. I expect user of this library has more chance to be familiar with Python. They can use ast.parse which returns the same AST. I think alignment gives more value than more describing name.
Enhancing parser error sounds very good idea as long as keeping consistency with SyntaxError for the same reason. I will keep using same token terms with tokenize module, but ParseError will not be part of that. Because Python doesn't expose error variant but only error messages, renaming variants will be a good idea. Appending more human friendly error messages to original messages will be too.
If you are also regarding it, I think renaming
CmpoptoCmpOpwill be good. It will not make document lookup harder but less confusing.DimitrisJim commentedon May 17, 2023
Though the intent is indeed a +1 I'd also stick with the ugly abbreviations due to the reasons YunWon states. Of course, non-public facing names with such a relation to Python can and should be as clear as possible.
youknowone commentedon May 17, 2023
Do you have good suggestions for new names of ParseErrorType variants?