Merge 'Object-oriented code' page into 'PHP coding standards' page

Created on 10 December 2024, 3 months ago

Problem/Motivation

There are 'main' PHP standards are across two pages. There is even a 'naming' section on both pages. This is confusing.

It was suggested in an issue somewhere to merge them.

Proposed changes

Move the docs from Object-oriented code to the PHP coding standards .

The details are not listed here because it will be a simple copy/paste.

Remaining tasks

Decide if this should be done or not.

📌 Task
Status

Active

Component

Documentation

Created by

🇳🇿New Zealand quietone

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

  • Issue created by @quietone
  • 🇬🇧United Kingdom jonathan1055

    That sounds like a reasonable plan. I expect the Object-oriented page is newer, maybe added when Drupal 8 was first being developed?

  • 🇳🇿New Zealand quietone

    There was also support in Slack for this from larowlan and yesct.

    I moved the content, then merged two 'naming' and two 'type hinting' sections. After that I took the liberty of alphabetizing the page by the h2 headings and ensured that all h2 headings had a correct id.

  • 🇦🇹Austria drunken monkey Vienna, Austria

    Great job, thanks!
    I’d merely suggest renaming the “Naming » Classes” sub-heading to “Classes, methods and properties”. I was a bit confused by properties missing from the “Naming” sub-menu.

  • 🇳🇿New Zealand quietone

    @drunken monkey, thanks.

    I tried something different and split that into 3 headings. What do you think?

  • 🇦🇹Austria drunken monkey Vienna, Austria

    Thanks for the suggestion! However, I’m not sure I’m convinced.
    In theory, it seems like a good idea to separate the rules for the two, but then the extra “Acronyms in a Class or Method name” section makes it awkward. You now have to read two sections for the naming conventions of a specific entity instead of one, which might make it easier to miss. It also looks a bit silly to have a section with just a single sentence.
    “Stand-alone name examples” being a sub-section of that also doesn’t make much sense, I guess it would make more sense to bump it up to an <h3>? Or maybe all four should be <h4> under a new <h3>Object-oriented code</h3> heading (or similar)? The first half of the example could even be nested under “Classes and Interfaces”, as it only lists those.

    All in all, to me it seems like this creates more problems than it solves, tbh, if only because of the acronyms rule and the example code that is pertinent to both classes and methods. (Also, I guess the acronyms rule even applies to properties? Would be strange if it were XmlSource and getXml() but $extractedXML.)

  • 🇳🇿New Zealand quietone

    I can't quite translate the last comment to actual changes. But since this is now going beyond a merge of one page into another I have reverted the split of the headings. I have changed the heading 'Classes' to "Classes, Methods and Properties" as suggested in #4. So let's go with that.

    The examples that go along with this should be improved but should be a separate issue.

Production build 0.71.5 2024