Add guidelines for naming packages

[jiahao]

Ref: https://groups.google.com/forum/#!topic/julia-dev/Qw1eaMUKYas

Guidelines courtesy of @johnmyleswhite and @joehuchette

[stevengj]

DataVisualization seems like a bad example since we will certainly have multiple visualization packages forever.

[johnmyleswhite]

Maybe use Convex as our example, especially after it changed its name from CVX to Convex?

[mlubin]

The reason for the name change from CVX to Convex was on request from the author of the CVX matlab package, not for increased clarity. I'd also claim that Convex.jl is one particular way to model convex optimization and isn't the "unique source of truth", so I'm not sure it's a good example.

[mpastell]

About 2. : Why would the package names need to be plural in general? I think a lot of the names currently aren't.

[kmsquire]

@mpastell, it's not that they need to be, but currently (and into the foreseeable future), a package cannot contain a type with the same name as the package. This is because the name of the module itself is included as a constant symbol within the package namespace.

julia> module MyTest
       end

julia> names(MyTest)
1-element Array{Symbol,1}:
 :MyTest

julia> module MyTest
       type MyTest end
       end
Warning: replacing module MyTest
ERROR: invalid redefinition of constant MyTest

So if you want to create a type with the name SuperFilter, an easy way to name the package similarly is to pluralize it to SuperFilters. (John gave the examples of DataFrames.DataFrame and BloomFilters.BloomFilter above.)

[tkelman]

The if you want to define a type in your package with a similar name part doesn't apply to all packages though. If your package is named such that you will want to do that, then yes making the package name plural makes perfect sense as a way to accomplish it. I don't think it should be a hard-and-fast rule, I'm trying to find a legalese document that starts out by defining various "should" "shall" "must" terminology to see if there's a weaker way of recommending plural names.

[kmsquire]

@tkelman, agreed.

[tkelman]

Maybe just reverse the sentence? If you want to define a type in your package with a similar name to the package itself, then the package name should be plural.

[johnmyleswhite]

I do think there's something to be said for a consistency principle that keeps most package names plural since that means you don't have to debate when the name shouldn't be plural. Moreover, the phrase using Foo in English often sounds ungrammatical when Foo is a noun and it's singular. using Spoons makes sense; using Spoon doesn't.

[jiahao]

Moreover, the phrase using Foo in English often sounds ungrammatical when Foo is a noun and it's singular.

On one hand we have packages like DataFrames that provide the ability to instantiate more than one DataFrame type, but conversely, we also have packages like JuliaParser which do not provide a new eponymous type, but rather new functions. Arguably, using JuliaParsers; JuliaParsers.parse(blah) sounds odder than the singular variety since a user would expect there to only be one canonical parser.

[mlubin]

IMHO a policy favoring plural names will lead to some bizarre choices. It's fine to state it as a suggestion, but I would give the package authors some leeway to decide if a plural name really makes sense and is necessary on a case by case basis.

[jiahao]

I've updated the guidelines taking into account the discussion so far. Hopefully some of the new examples are more sensible.

[mpastell]

I thinks thats much better!

[kmsquire]

+1

[jlapeyre]

The flat package (module) name space will probably get very crowded quickly (are submodules ever distributed separately?). And I suppose it will be common for assumptions about package relations or which application domains will want to use a name to be wrong. Apparently perl has 108K modules . Here is a list of 53K python modules. Will the current scheme of organizing and naming Julia packages have to be changed when there are 10,000 Julia packages ? The relation between packages/modules/name spaces, etc. in a particular language will influence how packages are organized.

The first sentence of the van Rossum style guide for naming conventions for Python is "The naming conventions of Python's library are a bit of a mess, so we'll never get this completely consistent..." (but this does not address class hierarchy so much) Here is a proposal for Naming conventions and recipes related to packaging in python.

Perl module file names always encode a name space hierarchy. Some python packages do and some don't--- the idea is to avoid unneeded verbosity. Some people say java class names are overly verbose; others say they planned for big growth. Is one of these a good model for Julia ?

[stevengj]

"even if" → "even though", since there's no doubt that the latter are shorter.

[jiahao]

bump

[mlubin]

No objections here.

[joehuchette]

Looks great.

[StefanKarpinski]

💯

[tkelman]

backported in 5c065e7