From e39ff83b406f52195cf506a48cfc69c7b0aeb838 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Mon, 2 Jan 2017 22:32:30 -0500 Subject: [PATCH] Rework constructor section in manual My writing style has changed quite a bit since this was first written. * doc/classes.text (Constructors): Reword section. Remove reference to static classes and singletons (we do not want to encourage such things). Add mention of good constructor practices. --- doc/classes.texi | 78 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 54 insertions(+), 24 deletions(-) diff --git a/doc/classes.texi b/doc/classes.texi index 46c7662..809416e 100644 --- a/doc/classes.texi +++ b/doc/classes.texi @@ -461,17 +461,26 @@ is functionally no difference between named and anonymous classes.} Much better! We now have a useful error message and immediately know which class is causing the issue. + @node Constructors @subsection Constructors -A ``constructor'' in JavaScript is simply a function---whether or not -it actually constructs a new object depends on whether the @code{tt} -keyword is used. With ease.js, constructors are handled in a manner -similar to most other languages: by providing a separate method. +ease.js defines object constructors in a manner consistent with many + other classical object-oriented languages: + a specially named method on the@tie{}class. -Until the release of ECMAScript@tie{}6, which introduced the @code{class} -keyword, there was no convention for constructors defined in this -manner. The implementation ease.js chose is very similar to that of -PHP's (@pxref{Constructor Implementation}): +Traditionally, a ``constructor'' in JavaScript is a function intended to + initialize a new object when invoked with the@tie{}@code{new} + keyword. +That function also contains a @code{prototype} property that defines the + object's prototype. +ECMAScript@tie{}6, + with the introduction of the@tie{}@code{class} keyword, + provided a standard @code{constructor} method that generates + constructor for the prototype. + +ease.js was written long before ES6 was ratified. The implementation +it chose is very similar to that of PHP's (@pxref{Constructor +Implementation}), using a @code{__construct}@tie{}method: @float Figure, f:constructor @verbatim @@ -494,15 +503,17 @@ PHP's (@pxref{Constructor Implementation}): @end float ease.js introduced the @code{constructor} method in version@tie{}0.2.7 -to match the ES6 ``class'' implementation; it is an alias for -@code{__construct}. This method name may be used prior to ES6. + to match the ES6 ``class'' implementation; + it is an alias for @code{__construct}, + and they may be used interchangeably. +This method name may also be used prior to ES6. @float Figure, f:constructor-es6 @verbatim // ECMAScript 6 syntax let Foo = Class( 'Foo', { - // you may still use __construct + // you may still use __construct if you'd prefer, as shown above constructor( name ) { console.log( 'Hello, ' + name + '!' ); @@ -518,23 +529,31 @@ to match the ES6 ``class'' implementation; it is an alias for @caption{Declaring constructors in an ECMAScript 6 style} @end float -When the class is instantiated, the constructor is invoked, permitting you -do to any necessary initialization tasks before the class can be used. The -constructor operates exactly how you would expect a constructor to in -JavaScript, with one major difference. Returning an object in the -constructor does @emph{not} return that object instead of the new class -instance, since this does not make sense in a Class-based model. +The constructor is invoked just after the class is instantiated, + allowing for necessary initialization tasks before the class can be + used. +It is good practice to use the constructor @emph{only} for + initialization that is critical to the object's integrity (such as + initializing internal state). +It is considered poor design for the constructor to have side-effects; + that is, + the act of instantiating an object should not manipulate global + variables or the environment. -If you wish to prevent a class from being instantiated, simply throw an -exception within the constructor. This is useful if the class is intended to -provide only static methods, or if you wish to enforce a single instance -(one means of achieving a Singleton). +The constructor operates exactly how you would expect a constructor to + in JavaScript, + with one important difference: + returning an object in the constructor does @emph{not} return that + object in place of the new class instance. + +If you wish to prevent a class from being instantiated, + simply throw an exception within the constructor. @float Figure, f:constructor-prevent @verbatim var Foo = Class( 'Foo', { - 'public __construct': function( name ) + __construct: function( name ) { throw Error( "Cannot instantiate class Foo" ); } @@ -543,8 +562,19 @@ provide only static methods, or if you wish to enforce a single instance @caption{Prevent class from being instantiated} @end float -Constructors are optional. By default, nothing is done after the class is -instantiated. +Constructors are always public; + there is no harm in explicitly specifying the keyword, + but it's usually omitted for brevity. +It is not permitted to make a constructor protected or private + (@pxref{Access Modifiers}). + +Constructors are optional, + and no constructor is defined by default.@footnote{ + That is, no user-facing constructor is defined by default; + ease.js handles plenty of its own internal tasks during + construction, + which cannot be overridden or inhibited.} + @node Temporary Classes @subsection Temporary Classes