Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Me being a slight grammar nazi :) #23

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Me being a slight grammar nazi :) #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions content/maintainability1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ <h3>Do not expose implementation details</h3>
})();
</pre>

<p>A common pattern for classes (e.g. <a href="http://book.mixu.net/ch6.html">objects instantiated from a prototype</a>) is to simply mark class methods as private by starting them with a underscore. You can properly hide class methods by using .call/.apply to set "this", but I won't show it here; it's a minor detail.</p>
<p>A common pattern for classes (e.g. <a href="http://book.mixu.net/ch6.html">objects instantiated from a prototype</a>) is to simply mark class methods as private by starting them with an underscore. You can properly hide class methods by using .call/.apply to set "this", but I won't show it here; it's a minor detail.</p>

<h3>Do not mix definition and instantiation/initialization</h3>

Expand All @@ -154,7 +154,7 @@ <h3>Do not mix definition and instantiation/initialization</h3>
module.exports = FooObserver;
</pre>

<p>While this is a proper module (I'm excluding the wrapper here), it mixes initialization with definition. What you should do instead is have two parts, one responsible for definition, and the other performing the initialization for this particular use case. E.g. <code>foo_observer.js</code></p>
<p>While this is a proper module (I'm excluding the wrapper here), it mixes initialization with definition. What you should do instead is have two parts: one responsible for definition, and the other performing the initialization for this particular use case. E.g. <code>foo_observer.js</code></p>

<pre class="prettyprint">
function FooObserver() {
Expand Down Expand Up @@ -326,7 +326,7 @@ <h2>Building an application out of packages</h2>

<h2>Using the glue build system</h2>

<p>So, now we have a somewhat detailed spec for how we'd like to build. Node has native support for require(), but what about the browser? We probably need a elaborate library for this?</p>
<p>So, now we have a somewhat detailed spec for how we'd like to build. Node has native support for require(), but what about the browser? We probably need an elaborate library for this?</p>

<p>Nope. This isn't hard: the build system itself is about a hundred fifty lines of code plus another ninety or so for the require() implementation. When I say build, I mean something that is super-lightweight: wrapping code into closures, and providing a local, in-browser require() implementation. I'm not going to put the code here since it adds little to the discussion, but <a href="https://github.com/mixu/gluejs/blob/master/lib/glue.js">have a look</a>.</p>

Expand Down Expand Up @@ -368,7 +368,7 @@ <h2>Including files and building a package</h2>

<h2>Binding to global functions</h2>

<p>We often want to bind a particular name, like <code>require('jquery')</code> to a external library. You can do this with <code>replace(moduleName, string)</code>.</p>
<p>We often want to bind a particular name, like <code>require('jquery')</code> to an external library. You can do this with <code>replace(moduleName, string)</code>.</p>

<p>Here is an example call that builds a package in response to a HTTP GET:</p>

Expand Down
6 changes: 3 additions & 3 deletions content/maintainability2.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,13 +48,13 @@ <h3>Refactoring an existing module</h3>

<p>4. Delay concrete instatiation as long as possible by extracting module state setup into a single bootstrap file/function. Defining a module should be separate from running the module. This allows small parts of the system to be tested independently since you can now require your module without running it.</p>

<p>For example, where you previously used to define a class and then immediately assign a instance of that class onto a global variable/namespace in the same file; you should move the instantatiation to a separate bootstrap file/function.</p>
<p>For example, where you previously used to define a class and then immediately assign an instance of that class onto a global variable/namespace in the same file; you should move the instantatiation to a separate bootstrap file/function.</p>

<p>5. If you have submodules (e.g. chat uses backend_service), do not directly expose them to the layer above. Initializing the submodule should be the task of the layer directly above it (and not two layers above it). Configuration can go from a top level initialize() function to initialize() functions in submodules, but keep the submodules of modules out of reach from higher layers.</p>

<p>6. Try to minimize your external surface area.</p>

<p>7. Write package-local tests. Each package should be have unit and integration tests which can be run independently of other packages (other than 3rd party libraries and the common package).</p>
<p>7. Write package-local tests. Each package should have unit and integration tests which can be run independently of other packages (other than 3rd party libraries and the common package).</p>

<p>8. Start using npm with semantic versioning for distributing dependencies. Npm makes it easy to distribute and use small modules of Javascript.</p>

Expand All @@ -75,7 +75,7 @@ <h2>Guidelines for new projects</h2>

<h2>Tooling: npm</h2>

<p>Finally, let's talk about distribution. As your projects grow in scope and in modularity, you'll want to be able to load packages from different repositories easily. <a href="http://npmjs.org/">npm</a> is an awesome tool for creating and distributing small JS modules. If you haven't used it before, Google for a tutorial or <a href="http://npmjs.org/doc/">read the docs</a>, or check out <a href="http://blog.nodejitsu.com/npm-cheatsheet">Nodejitsu's npm cheatsheet</a>. Creating a npm package is simply a matter of following the CommonJS conventions and adding a bit of metadata via a <code>package.json</code> file. Here is an example <code>package.json</code></p>
<p>Finally, let's talk about distribution. As your projects grow in scope and in modularity, you'll want to be able to load packages from different repositories easily. <a href="http://npmjs.org/">npm</a> is an awesome tool for creating and distributing small JS modules. If you haven't used it before, Google for a tutorial or <a href="http://npmjs.org/doc/">read the docs</a>, or check out <a href="http://blog.nodejitsu.com/npm-cheatsheet">Nodejitsu's npm cheatsheet</a>. Creating an npm package is simply a matter of following the CommonJS conventions and adding a bit of metadata via a <code>package.json</code> file. Here is an example <code>package.json</code></p>

<pre class="prettyprint">
{ "name": "modulename",
Expand Down