Skip to content

Commit

Permalink
Add discussion of factory functions & methods
Browse files Browse the repository at this point in the history
---
Signed-off-by: Michael Ferguson <mppf@users.noreply.github.com>
  • Loading branch information
mppf committed Aug 5, 2022
1 parent 3c50240 commit 9a9f446
Showing 1 changed file with 27 additions and 0 deletions.
27 changes: 27 additions & 0 deletions doc/rst/developer/bestPractices/StandardModuleStyle.rst
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,33 @@ Many paren-ful methods take some notable action. Try to make these
methods method names be a verb. In particular, a method that modifies an
argument in-place should be a verb.

Factory Functions and Methods
+++++++++++++++++++++++++++++

Factory functions or methods are procedures where the main purpose of
that procedure is to create a new object or value. There are many other
procedures that return a value but construcing that value is not the main
purpose of the function. For example, 'open' and 'spawn' are not factory
functions -- the main action of these methods is to work with the OS to
open a file or launch a subprocess.

In many cases factory procedures are not needed. Regular initializers
will work just fine to support the pattern of ``new Something(...)``.
Type conversion is best supported by creating a cast (``:``) operator
overload.

One case in which factory procedures are useful is when it is awkward to
distinguish between several ways of creating something based on the
initializer arguments alone.

Factory procedures should have a name that begin with 'create'.

Factory procedures can be functions or type methods. For example, we
could have:

* ``createStringWithBorrowedBuffer`` or
* ``string.createWithBorrowedBuffer``.

Other Identifiers
-----------------

Expand Down

0 comments on commit 9a9f446

Please sign in to comment.