Add file naming conventions to docs

[Tbusk]

Hi, there doesn't seem to be a consensus on what the file naming convention for vala source files is.

Elementary OS has PascalCase as what they view as desirable.
https://docs.elementary.io/develop/writing-apps/code-style#classes-and-files

The Vala for C# developers page seems to show everything BUT the file naming convention.
https://docs.vala.dev/developer-guides/documentation/vala-for-csharp-devs/03-naming-conventions.html

Additionally, the page that goes into compilation and source files also does not touch on what is desirable / expected for the file naming convention.
https://docs.vala.dev/tutorials/programming-language/main/02-00-basics/02-01-source-files-and-compilation.html

As a community, especially in documentation, one path should be chosen for uniformity.

[SpikedPaladin]

kebab-case is the only way (without namespace in name ofc)

[edwood-grant]

My two cents. There are, I think, two options here:

1. We aim for the Elementary style standard, which I think its nice and its an active ongoing project with lots of repos to check out, so using that style makes sense. https://docs.elementary.io/develop/writing-apps/code-style

Example for a ThisIsAnExampleClass -> ThisIsAnExampleClass.vala

2. Use the internal vala style withing gitlab, which is based on GNOME on some parts, on C# on some others, and non-committal on others. In particular it doesn't make a decision on filenames. But in practice the just use the whole name without spaces https://gnome.pages.gitlab.gnome.org/vala/manual/overview.html#vala-conventions

Example ThisIsAnExampleClass -> thisisanexampleclass.vala

I'm inclined to go for Elementary, mostly because it is much more specific, and also because most production code you could actually see now uses elementary code-style. Vala project style seems difficult to read and not common (and harder for C# users to grasp)

In fact, probably grabbing a lot of Elementary code-style conventions for the docs could be a good idea here IMO. Although there could be some issues regarding GObject style conventions and whether you should inherit from GLib.Object or not (it clear from a vapi perspective that you don't and no GObject-style, but not that easy from a normal user perspective on why use GLib.Object or not, or whether you actually should or should not).. but I'm digressing.

NOTE: I do find that, for vapis, kebab-case is the one people mostly use (to match meson conventions I think?), so I would also add a convention for that specific use case.

[nyx-lyb3ra]

I don't feel we should choose a convention at Vala level, but rather continue to allow each Vala user community to choose their own convention.

In GNOME they will certainly continue to use GObject conventions, and the Vala compiler itself uses one of them, but then elementary uses PascalCase.

Let them be free to choose the convention they like best, and at most, let's make the documentation descriptive of the conventions already in use.

Edit: For reference, the GObject conventions are documented here: https://docs.gtk.org/gobject/tutorial.html#boilerplate-header-code

... yeah, it's not the best place

[Tbusk]

I don't feel we should choose a convention at Vala level, but rather continue to allow each Vala user community to choose their own convention.

In GNOME they will certainly continue to use GObject conventions, and the Vala compiler itself uses one of them, but then elementary uses PascalCase.

Let them be free to choose the convention they like best, and at most, let's make the documentation descriptive of the conventions already in use.

Edit: For reference, the GObject conventions are documented here: https://docs.gtk.org/gobject/tutorial.html#boilerplate-header-code

... yeah, it's not the best place

@nyx-lyb3ra Well, the current solution is not mentioning anything. If the choice is to not pick a convention, then a better option would be to at least mention conventions vary by community, and then provide a link to some of the top community standards.

[nyx-lyb3ra]

@Tbusk that's why I said

let's make the documentation descriptive of the conventions already in use

:p