DOCS Update contribution guidelines around method visibility

This is in response to the RFC discussion in #8996
This commit is contained in:
Guy Marriott 2019-10-21 11:00:16 -07:00 committed by GitHub
parent 33a28394d6
commit 6458697663
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -144,6 +144,16 @@ Put code into the classes in the following order (where applicable).
* Template data-access methods (methods that will be called by a `$MethodName` or `<% loop $MethodName %>` construct in a template somewhere) * Template data-access methods (methods that will be called by a `$MethodName` or `<% loop $MethodName %>` construct in a template somewhere)
* Object methods * 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 ## SQL Format
If you have to use raw SQL, make sure your code works across databases. Make sure you escape your queries like below, If you have to use raw SQL, make sure your code works across databases. Make sure you escape your queries like below,