Name convention for acryonims

[asterite]

Right now we have:

• Xml::Node, Xml::Document, ...
• Json::Parser, Json::Lexer, ...
• HTTP::Client, HTTP::Request, ...
• Yaml::Parser, ...

Our original idea was to use upcase for things that you normally say letter by letter, like XML and HTTP, and use downcase for things that are pronounced like a name (json is pronounced "jason", yaml is pronounced "yaml", etc.).

We are currently following this rule, except for Xml, probably because we thought about that rule later in time. Now I'm not sure about this. I think Http::Client feels more lightweight than HTTP::Client. Maybe using downcase everywhere is better: you spend less time holding shift, and you can better distinguish where the next "word" starts when not using colons.

As a separate issue, I find it easier to type HttpClient than Http::Client, or JsonParser than Json::Parser. In .Net for example they have a type DateTime and another DateTimeKind that are related. They also have an HttpClient class. Right now we have Time and Time::Kind. I find it a bit annoying to type those two colons. So maybe we should drop them in these cases. Who else is going to define a JsonParser or an HttpClient type at the top level? The std should be as pleasant to use as possible.

We should decide on this now that the language is still in version 0.x, where we can make breaking changes.

[jhass]

One advantage of namespacing the core libs that's not as apparent yet might be documentation. Having too many constants in the toplevel makes it harder to write a nice documentation interface for that allows to easily find everything there is about a certain section of the standard library. On the subjective side, having everything in one namespace doesn't feel very "clean" to me. And I don't mind the colons that much.

So Http::Client from my side.

[ioquatix]

Personally I prefer XML, JSON, JTTP, YAML. They are abbreviations. It is correct to write them this way.

[papamarkou]

If I am not mistaken, the double colons are designated to represent a syntactic feature of Crystal in cases such as HTTP::Client, correct? In my opinion, it makes the implementation cleaner to retain the double colons so as to have distinct namespaces, so would agree with @jhass's taste on this.

As for the choice of capitalization, I would say that in my opinion the most sensible choice is to adhere to the real acronym as this makes the reference to the external software-concept more intuitively obvious (so for example, I prefer JSON simply because this is how the format is officially known).

[asterite]

Thanks you all for your answers!!

I'm now more convinced to name things as JSON::Parser, HTTP::Client, XML::Reader and so on, because of all your arguments. In fact, the other day I wrote a JSON pretty printer but in the initial comment I was inclined to write "Reads JSON from STDIN" but it would not match the name "Json". So... yes, I definitely think now that JSON is better.

@waj, @bcardiff, do you agree?

[jhass]

If we set a constant/module/class name convention we also should set an accompanying path/filename convention. Ruby failed to do that, leading to things like require 'optparse' to get OptionParser or require 'fileutils' to get FileUtils, require 'ostruct' for OpenStruct, the list goes on.

I'd vote for making the Rails style convention:

• Foo -> foo.cr
• FooBar -> foo_bar.cr
• FOOBar::Baz -> foo_bar/baz.cr
• FooBar::Baz -> foo_bar/baz.cr

I think that gives the best compromise between retaining information and what people are used to from the Ruby world. For completeness sake there's the argument to do FOOBar::Baz -> FOOBar/Baz.cr since that fully retains information. Personally, I don't like case in my filenames though.

[waj]

+1

If we have to unify the names I prefer to uppercase them everywhere. Actually I don't remember exactly why we decided to go with the spelling rule :)

[ioquatix]

@jhass Totally agree, consistent naming is a good idea.

[asterite]

Then it's decided. I'll make the (breaking change) soon. Better now than later :-)

[bcardiff]

+1 for upcase and consistency. As @jhass I don't like case in my filenames.

[asterite]

@jhass about optparse and others, we've been careful to follow the convention you say, even if it "breaks compatibility" with Ruby. So we have option_parser, file_utils and string_scanner. But if you find a name that doesn't follow this, please let us know :-)

[jhass]

I think it would make sense at this point to set those conventions into stone by for example writing them into a CONTRIBUTING.md into the repo ;)

[asterite]

@jhass Yes, or a style guide.

Now that we have this name convention we have another small inconsistency in the std. We have:

require "net/http"

HTTP::Client.new ...

We also have Socket and TCPSocket classes. Should we...

1. Change things to require "net/http/client"; Net::HTTP::Client.new and require "net/socket"; Net::Socket...?
2. Drop the "net" namespace?
3. Other alternatives?

[jhass]

I'd go for dropping the net namespace.

Having require 'http' making HTTP::Client available is okay, because it means to require http.cr which by convention should require everything in its namespace to make the library it represents usable. require 'http/client' should work too thouh.

[ozra]

Oh, I got really late to this party, and I guess a breaking rename again will be hard to argue for?

I definitely think PascalCased acronyms are much more readable, thus more easily understandable and readable code. I would beg on my knees for Http, AstNode, etc. instead of ASTNode etc.

[mirek]

More arguments for PascalCase

• FooBar it's convertible to / symmetric with fooBar, foo_bar, foo-bar etc. FOOBar is not and makes automatic conversion impossible
• it requires 0 brain effort to name things, there are no arguments between alternatives because there aren't any; FOOBar on the other hand is left for interpretation. We are going to end up with people using FOOBar in one library and FooBar in other (we'll see FooBAR as well).
• difference between abbreviations and acronyms is blurred / they are mixed into one word; you end up not knowing if this postgres type decoder class should be called IPAddr or IPADDR; RegProc REGProc or REGPROC; MacAddr, MACAddr or MACADDR - with PascalCase this problem doesn't exist
• PascalCase is readable when joined TcpIpHttp, TCPIPHTTP is not.
• abbreviations and acronyms have their own capitalization rules it's hard to say which one should be used PNPDiscovery or PnPDiscovery, LOCCounter or LoCCounter, UUIDV4 or UUIDv4 - with PascalCase it's more straight forward
• FooBar can be plural FoosBars - looks good, but FOOsBars FOOsBARs FOOBARs not so much
• similarly FooOrBar looks good, FOOOrBar FOOAndBar doesn't and it's hard to read because there is no clear boundary
• acronyms with time become words so on the long enough timeline FOOBar will die or will change to FooBar anyway

[asterite]

I'm starting to agree with @ozra and @mirek . I believe pascal case for acronyms is easier to read and write and makes names more consistent and easier to figure out in case you need to use them. I always liked how this is handled in C#, basically use pascal case, and the standard library is very consistent about this. While searching this I even found a code convention guide for acronyms right in the docs.

I was about to say that we should start using this convention, using aliases for the current names to make upgrade easier and slower, but... looking at the standard library, modules as namespaces are used very well. We have JSON.parse, JSON::Parser, XML.parse, XML::Document, HTTP::Client, URI::Parser, etc. I think OpenSSL is the only case an acronym is used combined with another word, and in this case I don't think it's a bad way to name it because nothing else comes after the SSL part. Well, we also have IniFile, but that's an old class that never received much love, and I think it should be named INI.

This way is maybe better because it preserves the original name of the acronym, so it's more familiar (Json.parse, Http::Client, Uri, etc., look kind of odd)

So, what we can do and encourage is pascal case when names are combined into a single name, but otherwise use acronyms as module names and use them as namespaces.

[mirek]

I agree that there is something strangely nice about capitals in ruby'ish syntax, this lean chubbiness that goes well with begin? end blocks and just feels right.

Should we just change IniFile to INIFile to be consistent and close this discussion forever leaving naming convention as something along the lines "capitals preferred for acronyms, for abbreviations that are getting longer, especially ones following acronyms use pascal case". So for example IPAddr follows this convention and feels right.

[ioquatix]

Yes changing IniFile to INIFile is the right choice IMHO. Also, I'd prefer no abbreviations, e.g. IPAddress. It's less ambiguous in general, easier for people for who English is not their native language.