Consistency of naming, admin

Topic: Consistency of naming, admin (Read 9810 times) previous topic - next topic

0 Members and 1 Guest are viewing this topic.

Consistency of naming, admin

June 25, 2013, 09:50:07 am

I have this quick question for you. It has been pointed out every now and then, that admin controllers files are a bit inconsistently named. They have Manage* in almost all, and not all. They have no suffix ('ManageBoards.php", not "ManageBoards.controller.php"). "Manage" has been said to be useless, since they "all" have it.

IMO, '.controller.php' was missed and is a must. I expect all controllers, in addons as well as core, to be '.controller.php', as templates are '.template.php', and subs '.subs.php'. (and core - strictly core - files have nothing, i.e. Load.php is Load.php.)
How about 'Manage' bit? It'd be the same name without it, with the user controller... I'd keep it. In particular since we don't use namespaces, so there's no way to make a difference between Boards_Controller and ManageBoards_Controller.

Please state your thoughts, grumbles, hate mail, whatever you see fit.

Re: Consistency of naming, admin

Reply #1 – June 25, 2013, 09:58:12 am

At least switch it? BoardsManage_Controller.
Would make easier to type a letter and find the file you want...

Or Boards_Admin_Controller?

Re: Consistency of naming, admin

Reply #2 – June 25, 2013, 10:03:56 am

Whatever you guys call your sauces stuff, I'll find it confusing anyway.

Re: Consistency of naming, admin

Reply #3 – June 25, 2013, 10:07:19 am

Same feeling for theme stuff, but you already know that.

Re: Consistency of naming, admin

Reply #4 – June 25, 2013, 10:25:02 am

Currently:
ManageBoards.php (/sources)
ManageBoards.template.php (/templates)

Quote from: emanuele – June 25, 2013, 09:58:12 amAt least switch it? BoardsManage_Controller.
Would make easier to type a letter and find the file you want...
Or Boards_Admin_Controller?

BoardsAdmin.controller.php
BoardsAdmin.template.php

or,
BoardsManage.controller.php
BoardsManage.template.php

If files (not classes) change name, the template files names should change too, accordingly. Otherwise the correspondence is broken, and Ant will grumble that he won't find "the sources for".

Re: Consistency of naming, admin

Reply #5 – June 25, 2013, 11:19:11 am

I like BoardsManage better too. Easier to find file names in a quick glance as pointed out. And even allows you to key stroke to find it a little better. No problems renaming templates to match IMO.

Re: Consistency of naming, admin

Reply #6 – June 25, 2013, 03:13:35 pm

I'd personally favour

Code: [Select]

BoardsAdmin.controller.php
BoardsAdmin.template.php

but it's just a name and I'm fine with what the majority wants..

Re: Consistency of naming, admin

Reply #7 – June 25, 2013, 07:12:13 pm

Meh... yeah the more I think about it I do like BoardsAdmin better. It makes more sense and lets the user know it's a file that deals with administration.

Re: Consistency of naming, admin

Reply #8 – June 26, 2013, 02:46:14 am

admin.boards.controller.php ?

Re: Consistency of naming, admin

Reply #9 – June 29, 2013, 09:47:45 pm

All other file names are camel case, live. i.e. other controllers: https://github.com/elkarte/Elkarte/tree/master/sources/controllers

Re: Consistency of naming, admin

Reply #10 – July 20, 2013, 04:36:16 am

I started this https://github.com/norv/elkarte/tree/admin_rename/sources/admin (this branch won't remain, I'll meld commits differently, but just for you to see how it'd start to look like)

Apart from controllers (~30+ files) and templates (17 files). There are also:
Languages, for example: https://github.com/norv/elkarte/blob/admin_rename/themes/default/languages/ManageBoards.english.php (10 files)
These have to follow suit.

Several permissions (~6), for example: https://github.com/norv/elkarte/blob/admin_rename/sources/admin/AttachmentsAdmin.controller.php#L51
IMO these don't have to follow, they're not too many (afaics), and there are many other permissions used in admin (i.e. 'edit_news'). Yet, it's slightly less obvious which permission has to be checked for.

Hooks, for example: https://github.com/norv/elkarte/blob/admin_rename/sources/admin/AttachmentsAdmin.controller.php#L81
I didn't count these, but probably 30+, each admin controller has at least the hook for its main action handler.
On hooks, they'd kinda have to follow suit, because when controllers become 'BoardsAdmin_Controller', there isn't anything around to justify the hook 'integrate_manage_boards'... ponders
But hooks compatibility must be kept. Which can be done (in the [not-yet-there] hooks class).

ETA: a few $txt indexes. IMO no change.

ETA2: areas, ?action=admin;area=manageattachments
These are 6, it seems, everything else is already like ?action=admin;area=smileys

Just a heads up. Thoughts welcome.

Re: Consistency of naming, admin

Reply #11 – July 24, 2013, 05:17:50 pm

I am experimenting another option here. Because the number of changes was high, small but many, files and various small stuffs in the files, and the results don't seem that helpful on all accounts. Also, they're affecting addons too (indirectly at least).

So, back to the drawing board and the original post. I have asked myself if we can do this with less changes, and still capture as much as possible some consistency, some easiness - at least to navigate and use the files.
I made another branch, with this approach:
https://github.com/norv/elkarte/tree/admin_rename3

This is almost a minimum-changes branch, to answer issues of consistency, but not go much further than that, on existing habits - in the measure of possible.

In this branch:
All controllers are now .controller.php.
No change to ManageSomething: so ManageBoards is ManageBoards.controller (and template, and eventually language), and not BoardsAdmin.controller.
No change from 'Manage' to 'Admin' to templates, languages (since there's no longer why). A few exceptions below.

It captures the controller/template/[.subs/.class]/language pattern.
It has some refactoring of ScheduledTask, Subscriptions, and such, to bring them too up to the level of the others.
*Simple names*: several admin files didn't have "Manage" (for example Packages). This has been pointed out to me as inconsistency. But, in this branch, I kept this as it was, and even added to it, a few files like ManageCoreFeatures -> CoreFeatures.

Please browse the branch, and see if this may work out for you, or is it [insert here too few changes, confusing, too inconsistent, whatever].
https://github.com/norv/elkarte/tree/admin_rename3/sources/admin
https://github.com/norv/elkarte/tree/admin_rename3/themes/default

Re: Consistency of naming, admin

Reply #12 – July 24, 2013, 05:21:50 pm

To explain this last bit. This used to be the case because these are only admin sections, they don't have a "user" counter-part, they're not pages to manage something which is also available to users actions. They're just some pages available only in admin. They're not "all with Admin or Manage", but the idea behind them is like: admin pages which manage something which users act upon (i.e. Posts), are named ManagePosts, those which handle stuff admin-only, Packages, are Packages.
In this branch, I kept this idea, and expanded upon it. I've simplified a few other names: "ManageCoreFeatures" becomes simpler, "CoreFeatures". Well, it's two-words (apart from "_controller"), it ain't three. And Core Features is the core features area, no other like it in the UI. Same for a few others. ManageMaintenance -> Maintenance etc. (For templates and if any, language too.)

=> This branch won't solve the keyboard issue (sawwrry!), and it won't prettify them, but it will simplify them where possible. The main points of this approach are simplicity and minimum changes.

I'll note, I'm torn on the "Manage"/"Admin" missing. But also since they're in /admin, to have them all (33 files of 35) with Manage/Admin is also slightly redundant. I'll try to look at it from more perspectives.

Anyway. Please note a last bit, I'd prefer to "freeze" them, that is, the PR I'll make is meant to solve this topic without WIPs. So consider it this way: one of these is what we'll work with in 1.0 and 2.0 major versions.

Re: Consistency of naming, admin

Reply #13 – July 27, 2013, 04:00:53 pm

Quick cross-ref: https://github.com/elkarte/Elkarte/pull/749

(I know we know, but just for some other time

)

Re: Consistency of naming, admin

Reply #14 – December 08, 2013, 04:21:13 am

I suppose for 1.x line we have to keep naming stable, so unless there are big issues we can consider this close, right?