Case convention for the standard library

[perimosocordiae]

Right now the code in stdlib/ contains a mishmash of styles, with UpperCamelCase and snake_case most predominant. We should decide on a common case convention for:

• local variables
• constants
• free functions
• type parameters
• generic placeholders (~`T)
• structs
• struct members
• scopes
• scope blocks
• exported vs module-local versions of each of the above

I don't have a concrete proposal yet, but here are some miscellaneous thoughts on the topic:

• As of now, reserved keywords are almost entirely single-word lowercase. If we use UpperCamel it's very clear what is a keyword and what is user-defined.
• The scopes in core.ic are all lowercase to mimic C-like languages (for, if, while, etc.) On the other hand, the scopes in file.ic are upper-cased (With and Lines) because they're not mimicking anything in particular.
• The foreign functions defined in stdlib/c/ are generally named identically to their foreign counterpart (atoi, double, isdigit, etc.)

Finally: whatever convention we decide to follow for stdlib code is very likely to become the convention for all Icarus code. We should do our best to make it readable, convenient to use, and easy to remember.

[asoffer]

• As of now, reserved keywords are almost entirely single-word lowercase. If we use UpperCamel it's very clear what is a keyword and what is user-defined.

I think we should consider this a non-concern. Builtins do not need to prime syntactic real estate. Zig prefixes them with @. C++ prefixes them with underscores. I don't think ours will be as hidden as they are in C++, but nevertheless, they should take a backseat to library code.

[asoffer]

Naming conventions, some common, some I just made up for this post, so we have a language with which to talk about these options.

• snake_case
• camelCase
• PascalCase
• hyphen-case
• SHOUTING_CASE
• __double_under_case__
• _pre_snake_case
• post_snake_case_

Thoughts:

• There's value in post snake case for struct fields, giving them some visual separation from the object of which they are a field.
• public symbols that are intended to be used outside the current module should be the simplest because they are interacted with the most. To me the simplest are snake, camel, and pascal.
• we should not have separation between functions and values as is done in the Google C++ style guide, because the distinction is hazy with functors and callable objects.
• Deviating from the spellings for, if, and while provide no value and have very high cost to the learning curve. This makes me think scopes should generally be snake or camel case.
• Types are values so we should not distinguish spelling.
• constants are meaningfully different from variables and could be a useful distinction. Note that types and functions are often constants but not always.
• like scopes, there is value in keeping foreign functions matching the spelling in other languages. If we're mostly pulling from C this means snake case. But I also thing it makes more sense to carve these out as exceptional if need be rather than have them dictate the conventions globally.
• perhaps it's just familiarity, but simple getters/setters shouldn't need capitalization.

[perimosocordiae]

One category that I forgot about in my initial list: module names. We currently use snake_case for modules, but this runs the risk of name clashes (especially for constructions like c ::= import "c/stdio.ic"). I know that technically modules are just values like everything else, but a syntactic distinction may be useful.

[asoffer]

I suspect it will be rare for the standard library to export modules, so the naming convention here shouldn't matter too much. That being said, I'd like to aim for the standard library to be readable just like "normal code" and so it's possible that whatever conventions we choose will be copied.

In my mind the bigger concern is that modules will be spelled frequently and should therefore be unobtrusive. If we make them annoying to spell (e.g., something horrible like RoLlErCoAsTeRcAsE, users will opt for embedding the module with -- ::= import "xyz". This isn't as horrible as using namespace in C++, but it still probably produces a worse reading experience in most cases.