Refactoring JavaScript: parsing source code syntax and semantics to generate CRC Models

Create Class-Responsibilities-Collaborators (CRC) Models to improve the design of existing code.

Table of contents

• CRC Models for understanding and refactoring JavaScript code-bases
• Refactoring defined
• Class-Responsibilities-Collaborators (CRC) Models
• Natural to constructed language translation (and visa versa) is hard
• Natural to constructed language translation is insufficient
• Solution-focused problem solving, aka, "product delivery"
  • CRC Class defined
  • CRC responsibility statements
    • Conceptual graphs
  • CRC Collaborators
• Sample report from early v0.1.0 work

CRC Models for understanding and refactoring JavaScript code-bases

JavaScript can quickly become too complex and incomprehensible to maintain. Class-Responsibilities-Collaborators (CRC) Models provide a simple way to represent and understand your code-base so you can improve its design with refactorings.

Refactoring defined

In his seminal book, Refactoring: Improving the Design of Existing Code, Martin Fowler defined refactoring as a:

Noun: a change made to the internal structure of software to make it easier to understand and cheaper to modify without changing its observable behavior.

Verb: to restructure software by applying a series of refactorings without changing its observable behavior.

There are over 90 refactorings cataloged to-date. Refactorings are problem/solution techniques with formal names. Whenever you improve a code-based with a refactoring, you should include the refactoring's name in your commit message.

View the refactoring catalog for a alphabetical summary of 91 techniques that improve your source code.

Class-Responsibilities-Collaborators (CRC) Models

Design...concerns itself with the artificial world and uses modeling, pattern-forming, and synthesis to study it. In design, practicality, ingenuity, empathy, and a concern for "appropriateness" are the core values.

Clear, unambiguous, and effective communication is hard. Linguists have demonstrated the syntactic and semantic ambiguity of natural languages for centuries. As a consequence, constructed languages have emerged in order to communicate more precisely and accurately. Modern programming languages are recent examples of constructed languages.

All modern (Turing-complete) programming languages exhibit valid syllogistic reasoning. JavaScript is one of the most popular constructed languages on the planet, and JavaScript programmers execute valid conditional reasoning with constructed elements such as

• Objects
• Expressions
• Operators
• Statements
• Declarations
• Functions
• Classes
• Errors

Natural to constructed language translation (and visa versa) is hard

It turns out that human don't shine to constructed languages. Natural selection favored heuristic reasoning that errs on the side of survival. These heuristic patterns only share incidental similarities with formal logic. In fact, cognitive psychologists have proven that most people not only demonstrate difficulty with understanding modus ponens (affirming the antecedent); they remain resistant to exercising modus ponens even after they've formally studied it. [1] In short, syllogistic reasoning doesn't come naturally to humans.

Natural to constructed language translation is insufficient

Professional programmers and engineers learn how to exercise valid conditional reasoning as part of their trade. Valid reasoning is necessary, but it is not sufficient: expertise with conditional syllogisms does not teach us how to translate a hodgepodge of actions, facts, and goals -- also known as "requirements" -- into conceptual models that execute the purpose and intention lurking somewhere among all the User Stories. The extent to which product delivery teams are able to articulate a proposed product's purpose and intention often dictates the success or failure of the product itself.

Solution-focused problem solving, aka, "product delivery"

Fortunately an entire field of study exists to help us overcome the challenges of converting resources into products that meet objective goals. This field is called design.

1. Automated CRC Model reports with hyperlinks to associated source code.
2. Auto-generated Object responsibilities based on annotations, e.g., JSDoc @descriptions, git logs, etc.
3. Code smell detection, over time.
4. Refactoring recommendations with hyperlinks to popular refactoring catalogs (e.g., Refactoring Guru and Martin Fowler's Catalog of Refactorings).

5. Static source code metrics within time-ranges. These metrics must formally substantiate the previously mentioned goals to avoid data puke reports:

   a. Total/Average SLOC (source lines of code)

   b. Maintainability indexes for a CRC Model

   c. Cyclomatic complexity

   d. Halstead complexity measures

CRC Class defined

Classes are simply JavaScript Object and class identifiers.

CRC responsibility statements

CRC resposibilities express the semantic intent of source code.

Infer the purpose of software products based on data mined from:

1. AST structure
2. Identifier names
3. Code comments
4. Tests
5. Source control logs

Conceptual graphs

In order to infer and communicate the semantic intent lurking within source code, the application of semantic roles feels like a natural fit. John Sowa's Conceptual Graphs could be useful, not only for discovering and expressing the semantic intent of source code, but also for pointing out risks associated with inconsistent or even contradictory expressions of purpose (i.e., bad design).

CRC Collaborators

Collaborators are JavaScript Objects and classes used to fulfill a Class's responsibilities.

Sample report from early v0.1.0 work

This report was generated by the tests/crc-model-formatter.spec.js specs; a simple "es5-object-identification fixtures; and a lodash html template.