From 64586976635127e4502913caa89e8999a72b1149 Mon Sep 17 00:00:00 2001 From: Guy Marriott Date: Mon, 21 Oct 2019 11:00:16 -0700 Subject: [PATCH] DOCS Update contribution guidelines around method visibility This is in response to the RFC discussion in #8996 --- docs/en/05_Contributing/14_PHP_Coding_Conventions.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/en/05_Contributing/14_PHP_Coding_Conventions.md b/docs/en/05_Contributing/14_PHP_Coding_Conventions.md index 6f9fe6ab9..66ece1452 100644 --- a/docs/en/05_Contributing/14_PHP_Coding_Conventions.md +++ b/docs/en/05_Contributing/14_PHP_Coding_Conventions.md @@ -143,6 +143,16 @@ Put code into the classes in the following order (where applicable). * Controller action methods * Template data-access methods (methods that will be called by a `$MethodName` or `<% loop $MethodName %>` construct in a template somewhere) * Object methods + +## Method/property visibility guidelines + +When adding new methods and properties, should you make them public, protected, or private? + + * Public: Use this for public APIs. You should add tests and documentation for these. + * Protected: Use for extensibility APIs. Note that compatibility for such APIs should be maintained in minor releases, and so you'll probably want to cover them in tests (i.e. test that these methods can be called from within a subclass and/or overridden). If that seems like overkill, consider whether it's safer to leave these as private for now. + * Private: Use for class internals + +Above all, recognise that when you are making something public or protected, you are creating an API for other developers to use and rely on, and do so with care. Don't simply dump class internals in as protected members in the name of extensibility – doing so will be likely to break developers' projects in minor releases. ## SQL Format