Naming Convention

[aiverson]

I think we should pick a naming convention. I don't want to end up with randomly mixed naming conventions. The alllowercase naming convention used by most of the terra public API is consistent, but it isn't exactly the easiest to read. the mix of underscore_case into the private code in terra as well as in a few sections of the public API isn't very appealing either. We should pick one for this and stick to it. I'm a bit partial to using camelCase or underscore_case, possibly with PascalCase for structs with camelCase for variables and functions. Does anyone else have a preference or suggestion?

[capr]

underscore_case in implementation and alllowercase for the public API whenever possible.

[aiverson]

@elliottslaughter do you have any insight into the choice of naming conventions for the original Terra libraries to offer?

[elliottslaughter]

@capr's suggestion is what Terra uses, so it seems like a reasonable choice. My main gripe with using alllowercase for public APIs makes names hard to read. I think the main question is whether the upgrade in readability (to e.g. snake_case everywhere) is worth the inconsistency with Terra's main APIs.

[aiverson]

I'm willing to change all of Terra's main APIs to whatever naming convention we want if necessary. As long as I don't have to use alllowercase.

[elliottslaughter]

We could add aliases but I'd rather avoid breaking changes.

Anyway, I think it's ok for the standard library to use a different convention. My personal choice would be snake_case but I'm open to suggestions.

[aiverson]

Strange suggestion: What about PascalCase for composite type names, camelCase for methods of objects and entries of objects, snake_case for functions and variables that aren't OO members, and UPPER_SNAKE_CASE for constants.

I'm very happy with snake case, as long as we pick one, document it, and enforce it on PRs.

[capr]

change all of Terra's main APIs

a sure way to make yourself very unpopular among existing terra users :))

A quick note on consistency: I personally use snake_case for almost everything and yet sometimes I find that the underscore doesn't look right and I skip it. Sometimes I find that an abbreviated name is actually more popular in my head than the full version. And sometimes it's both rule violations in the same name, like how I'd rather say refcount than reference_count or ref_count, or how I'd rather say x, y, w, h than x, y, width, height. I do what feels right, and that may seem like a call to subjectivity, but I don't see it that way. It's more a trust in my intuitions that there are more complex rules at play here and applying a rigid simple rule over the entire matter would make things worse, not better.

[capr]

to make matters worse (or better), I'm not even following the UPPER_CASE for constants 100%, eg. I'd rather say inf and maxint than INF and MAX_INT, but I had to choose PI over pi (I would've used π if that were easy to type). Does that seem right to you? :))

[aiverson]

So, naming conventions are hard, and we should just try to make things reasonably sane? I'm not opposed to that. I'd still like to have a standard for consistency, but "always break consistency for intelligence" is a fine convention to have.

[Qix-]

👍 for snake case. Agreed with the point about all lowercase readability.

[elliottslaughter]

My inclination is to go with lower_snake_case for most names, and UPPER_SNAKE_CASE for constants, with the understanding that some discretion is allowed when that doesn't feel right for whatever reason. There is of course some subjectivity to all of this, but this seems reasonably Terra-ish and is consistent with at least the Terra libraries I'm familiar with.

[aiverson]

Alright. I've converted my work on the allocators over to that naming convention. I'm happy to declare that the official naming convention. Should I make a PR on terralib to offer snake_case aliases for everything reasonable?

[elliottslaughter]

Sure, go ahead.

[capr]

oh god

[elliottslaughter]

If you object, please speak now. :-)