From c28ea6474f7b4b7a9debea583ccd23b59a3ed668 Mon Sep 17 00:00:00 2001 From: "Sangwhan \"fish\" Moon" Date: Thu, 25 Jan 2024 16:27:48 +0000 Subject: [PATCH] Add guidance for factory method naming (#471) * Add guidance for factory method naming Resolves #378. * Update index.bs Co-authored-by: Amy Guy * Update index.bs Co-authored-by: Amy Guy * Update index.bs * Update index.bs Co-authored-by: Amy Guy * Update index.bs Co-authored-by: Amy Guy * Update index.bs Co-authored-by: Lea Verou * Update index.bs Co-authored-by: Sangwhan "fish" Moon * Update index.bs * Update index.bs * Update index.bs --------- Co-authored-by: Amy Guy Co-authored-by: Lea Verou --- index.bs | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/index.bs b/index.bs index 61ce4ce..af1de29 100644 --- a/index.bs +++ b/index.bs @@ -3444,6 +3444,37 @@ examples that violate the above rules are {{XMLHttpRequest}} and initialisms, even if they are repeated. +

Start factory method names with `create` or `from`

+ +Factory method names should start with `create` or `from`, optionally followed by a more specific noun. + +If a factory method constructs a new empty object, +prefix the method name with `create`. +However, if your factory method creates an object from existing data, +prefix the method name with `from`. + +Factory methods should be an exception, not the norm, and only used for valid reasons. +An example of valid usage of a factory method is +when an object is being created also requires association +with the parent object +(e.g. `document.createXXX()`). + +Use the prefix `from` +when there is a source object expected to be +converted to a target object. +For example, `Foo.fromBar()` would imply +that a `Foo` object will be created using a `Bar` object. + +A common pattern is to name generic factory methods `create()` or `from()`. + +Avoid inventing other prefixes +and using of legacy prefixes +unless there is a strong reason to do so. +A reason to make an exception would be to maintain consistency with +existing factory methods +under the same object, such as `document.initXXX()`. +New factory methods should not follow this convention. +

Warn about dangerous features

Where possible, mark features that weaken