Naming conventions for arrays of tables

[ChristianSi]

Consider the following array of tables, using the "plural" naming convention that's commonly used in the spec:

[[planets]]
name = "Mercury"
aphelion = 0.466697
radius = 2440

[[planets]]
name = "Venus"
aphelion = 0.728213
radius = 6052

[[planets]]
name = "Earth"
aphelion = 0.9832899
radius = 6371

[[planets]]
name = "Mars"
aphelion = 1.66621
radius = 3390

While here is the same file in "singular" convention:

[[planet]]
name = "Mercury"
aphelion = 0.466697
radius = 2440

[[planet]]
name = "Venus"
aphelion = 0.728213
radius = 6052

[[planet]]
name = "Earth"
aphelion = 0.9832899
radius = 6371

[[planet]]
name = "Mars"
aphelion = 1.66621
radius = 3390

Everybody: which convention do you prefer? For me it's clear that I prefer the "singular" convention since array each element describes a single item. Hence it seems strange (to me) having a plural "section header" followed by a single item.

Therefore I consistently use the singular convention in my TOML files. I wonder how others here see this? Do you prefer singular or plural?

If many prefer singular, it might be worth considering switching to singular style for the examples used by the spec. Since though the spec doesn't give any explicit naming tips (and it shouldn't), many will tend to follow the example shown there.

[arp242]

The more important question here of course is whether or not we should include Pluto in the list of planets.

---

Singular seems nicer in the TOML, but:

for planet in solar_system.planets {
    …
}

for planet in solar_system.planet {
    …
}

So in the code plural looks (much) better, IMO, so I'd choose that.

[eksortso]

@ChristianSi I much prefer the plural naming convention. The name of the array would be planets, and each element of the array would be a table that could would be accessible with for planet in planets in code, as @arp242 noted.

A case could be made for singular naming if just one element is expected. But it's still decoded as an array. An array of a single table, but still an array. If you don't mind reading planet[0] to get your single planet, then okay. But I do mind. Good coders ought to expect arrays to contain 0 or more elements and work accordingly.

Another case, coming from the database world, is that you give the array a singular name for the sake of convenience. You may have multiple database tables with plural names, so forcing singular names on your collections cuts down on the clutter of seeing "s" and "es" everywhere. But practically every dialect of SQL provides for table synonyms to keep that clutter out of your queries. With arrays of tables, I doubt that you would be juggling so many different kinds of them in a single TOML document that the same argument would apply.

Maybe those plural forms are visual clutter in TOML, and that [[planet]] makes sense when repeated. That would make sense as long as you remember that config["planet"] is an array of planets after parsing. And it would make sense if you saved yourself storage space by using shorter (singular) names. But config["planets"] visually indicates that you're dealing with any number of planets, and the amount of space you save is miniscule unless you're dealing with tens of thousands of entries, in which case you'd compress your data file anyway.

So I personally see no compelling reason to use singular names for arrays.

[marzer]

Plural style for me. It's consistent with how I would name a collection in any other context.

[ChristianSi]

You all think like programmers, not like TOML file writers. I'd argue that one should take the user perspective first, and put the programmer's way of thinking behind. For any general-purpose scenario, people will spend way more writing and editing TOML files that on the program code used to process them. So "How does it look and feel in the TOML file?" should be the relevant question.

[eksortso]

So "How does it look and feel in the TOML file?" should be the relevant question.

@ChristianSi Really shoulda said that first!

Cargo.toml in its documentation not only has array-of-table keywords that are all singular names (bin, batch, test, and example), but also goes out of its way to explain that multiples of each section are permitted. (Most likely this is because the [[array-of-tables]] syntax was new to users in general at the time.)

Chalk one up for singulars there. I'll mention that accompanying Cargo.lock uses singular names, but that file is machine-generated, so I'm not counting it.

pyproject.toml doesn't use double-bracket notation in its documentation, but arrays of inline tables are used. requires in [build-system] is an array of strings. That name is more of a verb than a noun, but consider it short for "requirements," why not.

And the metadata format fairly consistently uses plural names for container values. These include arrays of strings, arrays of inline tables, and tables whose keys are library names and whose values are version dependencies. I found just one exception (the dynamic keyword).

Plurals win, there. And this format came later than Cargo's, so they knew the precedents.

What are my feelings? Our specification actually uses both singulars and plurals in examples. I don't consider that a problem. If users can go either way and still feel comfortable, then I'm not too concerned about how we name table arrays in our examples.

Even if I like the plural name forms better.

[ChristianSi]

@eksortso:

Really shoulda said that first!

Well I certainly tried! That's why I gave that extensive example of how things look in the TOML doc, and why I wrote: 'Hence it seems strange (to me) having a plural "section header" followed by a single item.'

Kudos to the Cargo people for doing the right thing (as I would consider it) despite the bad example set by the TOML spec! Anyone knows of other projects that use the array of tables syntax – which naming style do they use for these?

pyproject.toml is irrelevant for the case discussed here, since (as you mention) they don't use the array of tables syntax at all. The only entries that could potentially use it seem to be authors/maintainers, but they explicitly state that those are to be written as "array of inline tables".

Our specification actually uses both singulars and plurals in examples.

I would be much more comfortable if that was true, but sadly, it isn't. All the array of tables examples use the plural convention – I count three different names: [[products]], [[fruits]], [[fruits.varieties]]; there is one case of [[fruit]], but it's in an example of invalid TOML and so certainly will not encourage people to use the singular style.

If the spec were to equally use both singular and plural style in its examples (say [[product]] in one case, [[fruits]] and [[fruits.varieties]] later, or the other way around) it could be considered as neutral regarding the naming conventions. Maybe we can agree that that would be an improvement?

[eksortso]

@ChristianSi I owe you an apology. My original review of toml.md skimmed over the example containing [[fruit]], which, as you noted, involves invalid TOML and thus does not apply to the overall impression of the array-of-table syntax and whether it should be demonstrated with singular or plural element names.

pyproject.toml is irrelevant for the case discussed here, since (as you mention) they don't use the array of tables syntax at all.

For the sake of style, use of singular or plural names is still relevant in general. pyproject.toml uses plurals when container values are expected. The only reason that this doesn't apply is that unlike the syntax generally used by the format, array-of-tables syntax references both the container and each individual element.

If the spec were to equally use both singular and plural style in its examples (say [[product]] in one case, [[fruits]] and [[fruits.varieties]] later, or the other way around) it could be considered as neutral regarding the naming conventions. Maybe we can agree that that would be an improvement?

Yes, I'd say, that would be an improvement. Want to go ahead and propose the changes in a new PR?

[ChristianSi]

OK, I'll do that!

[ChristianSi]

Done: #938.