search

backdrop-ops / docs.backdropcms.org

Website for displaying Backdrop CMS documentation and API source code.
https://docs.backdropcms.org/
6 stars 6 forks source link

Coding standards for object-oriented code #158

Closed bugfolder closed 3 years ago

bugfolder commented 3 years ago

From this Zulip discussion: questions about adding coding standards for object-oriented code to the documentation site.

It would go on this page, presumably as a new h2-level section of the page.

It was noted that Drupal has their own corresponding page, which we can borrow from, but there are some differences already (for example, autoloading).

bugfolder commented 3 years ago

I've taken a first cut at adapting the Drupal page, and to make it easily seeable, put it on docs.b.org as its own page (ultimately, it would go onto the PHP coding standards page).

https://docs.backdropcms.org/documentation/object-oriented-code-draft

Issues that I made some assumptions about but might warrant further discussion in this issue include:

Please comment further on anything I left out or got wrong.

herbdool commented 3 years ago

Thanks @bugfolder, this looks pretty good.

Maybe mention that a method's docblock should use {@inheritdoc} if the parent class has the same method.

I realized that the Layout classes aren't as good an example as the classes that use UserInterface which have all their properties and methods visibility declared.

One more thing, I'm not sure if we need to recommend putting .class.inc in the filename. I see a lot of classes that don't follow that.

bugfolder commented 3 years ago

I'm not sure if we need to recommend putting .class.inc in the filename. I see a lot of classes that don't follow that.

Even within Layout module, some do, some don't. I think, though, that nudging people toward a consistent standard is better than anything-goes, though, even if past inconsistencies are grandfathered in.

bugfolder commented 3 years ago

Thanks, @herbdool, for those comments; I've incorporated them, made a few more small changes and typo-fixes, and have added this material to the PHP coding standards page as a revision. And I've deleted the draft page since it's no longer needed.