WIP review checklist

README.md

@@ -3,6 +3,7 @@
 This repository contains the minimal set of code required to create your own custom Dash component.
 
 To create your own Dash component:
+
 1. Fork this repo
 2. Find-and-replace:
     1. `my_dash_component` with your component library name.
@@ -11,61 +12,76 @@ To create your own Dash component:
     4. `my-license` with your license (e.g. `MIT`)
     5. Rename the folder `my_dash_component/` with your component library name
 3. Install the dependencies:
-```
-npm install
-```
-4. Open up the JavaScript demo environment:
-```
-npm run start
-```
-5. Write your component code in `src/lib/components`. There is a sample component called `ExampleComponent.react.js` that you can use for inspiration. The demo app is in `src/demo` and you will import your example component code into your demo app.
-6. Test your code in a Python environment:
-    1. Build your code
+
     ```
-    npm run build:js-dev
-    npm run build:py
+    npm install
     ```
-    2. Run and modify the `usage.py` sample dash app:
+
+4. Open up the JavaScript demo environment:
+
     ```
-    python usage.py
+    npm run start
     ```
-7. Create a production build and publish:
+
+5. Write your component code in `src/lib/components`. There is a sample component called `ExampleComponent.react.js` that you can use for inspiration. The demo app is in `src/demo` and you will import your example component code into your demo app.
+
+6. Add custom styles to your component by putting your custom CSS files into your distribution folder (`my_dash_component`) and making sure that they are referenced in `MANIFEST.in` so that they get properly included when you're ready to publish your component.
+
+7. Test your code in a Python environment:
+    1. Build your code
+        ```
+        npm run build:js-dev
+        npm run build:py
+        ```
+    2. Run and modify the `usage.py` sample dash app:
+        ```
+        python usage.py
+        ```
+8. [Review your code](checklist.md)
+9. <span id="publishing">Create a production build and publish</span>
+
     1. Build your code:
-    ```
-    npm run build:js
-    npm run build:py
-    ```
+
+        ```
+        npm run build:js
+        npm run build:py
+        ```
+
     2. Create a Python tarball
-    ```
-    python setup.py sdist
-    ```
-    This distribution tarball will get generated in the `dist/` folder
+
+        ```
+        python setup.py sdist
+        ```
+
+        This distribution tarball will get generated in the `dist/` folder
 
     3. Test your tarball by copying it into a new environment and installing it locally:
-    ```
-    pip install my_dash_component-0.0.1.tar.gz
-    ```
 
-    4. If it works, then you can publish the component to NPM and PyPI:
-    ```
-    npm run publish
-    ```
-    ```
-    twine upload dist/dash_component-0.0.1.tar.gz
-    ```
-8. Share your component with the community! https://community.plot.ly/c/dash
+        ```
+        pip install my_dash_component-0.0.1.tar.gz
+        ```
 
-# More details
-- Include CSS files in your distribution folder (`my_dash_component`) and reference them in `MANIFEST.in`
-- The `tests` folder contains a sample integration test. This will run a sample Dash app in a browser. Run this with:
-    ```
-    python -m tests.test_render
-    ```
-    The Dash team uses these types of integration tests extensively. Browse the Dash component code on GitHub for more examples of testing (e.g. https://github.com/plotly/dash-core-components)
-- Publishing your component to NPM will make the JavaScript bundles available on the unpkg CDN. By default, Dash servers the component library's CSS and JS from the remote unpkg CDN, so if you haven't published the component package to NPM you'll need to set the `serve_locally` flags to `True`. We will eventually make `serve_locally=True` the default, [follow our progress in this issue](https://github.com/plotly/dash/issues/284).
-- Watch the [component boilerplate repository](https://github.com/plotly/dash-component-boilerplate) to stay informed of changes to our components.
+    4. Choose how you'd like to serve your library's CSS and JS (locally or via npm):
+
+        By default, Dash serves the component library's CSS and JS from the remote unpkg CDN. Publishing your component to NPM will make the JavaScript bundles available there. To publish to npm:
+
+        ```
+        npm run publish
+        ```
+
+        If you choose not publish the component's package to NPM you'll need to set the `serve_locally` flags in `usage.py` to `True`. We will eventually make `serve_locally=True` the default, [follow our progress in this issue](https://github.com/plotly/dash/issues/284).
 
+    5. Publish your component to PyPI:
+
+        ```
+        twine upload dist/dash_component-0.0.1.tar.gz
+        ```
+
+10. [Share your component with the community!](https://community.plot.ly/c/dash)
 
 # More Resources
-- Learn more about Dash: https://dash.plot.ly
-- View the original component boilerplate: https://github.com/plotly/dash-component-boilerplate
+
+-   Learn more about Dash: https://dash.plot.ly
+-   View the original component boilerplate: https://github.com/plotly/dash-component-boilerplate
+
+Watch the [component boilerplate repository](https://github.com/plotly/dash-component-boilerplate) to stay informed of changes to our components.

checklist.md

@@ -0,0 +1,46 @@
+# Code Review Checklist
+
+## Code quality & design
+
+-   Is your code clear? If you had to go back to it in a month, would you be happy to? If someone else had to contribute to it, would they be able to?
+
+    A few suggestions:
+
+    -   Make your variable names descriptive and use the same naming conventions throughout the code.
+
+    -   For more complex pieces of logic, consider putting a comment, and maybe an example.
+
+    -   In the comments, focus on describing _why_ the code does what it does, rather than describing _what_ it does. The reader can most likely read the code, but not necessarily understand why it was necessary.
+
+    -   Don't overdo it in the comments. The code should be clear enough to speak for itself. Stale comments that no longer reflect the intent of the code can hurt code comprehension.
+
+*   Don't repeat yourself. Any time you see that the same piece of logic can be applied in multiple places, factor it out into a function, or variable, and reuse that code.
+*   Scan your code for expensive operations (large computations, DOM queries, React re-renders). Have you done your possible to limit their impact? If not, it is going to slow your app down.
+
+## Component API
+
+-   Have you tested your component on the Python side by creating an app in `usage.py` ?
+
+    Do all of your component's props work when set from the back-end?
+
+    Should all of them be settable from the back-end or are some only relevant to user interactions in the front-end?
+
+-   Have you provided some basic documentation about your component? The Dash community uses [react docstrings](https://github.com/plotly/dash-docs/blob/master/tutorial/plugins.py#L45) to provide basic information about dash components. Take a look at this [Checklist component example](https://github.com/plotly/dash-core-components/blob/master/src/components/Checklist.react.js) and others from the dash-core-components repository.
+
+    At a minimum, you should describe what your component does, and describe its props and the features they enable.
+
+    Be careful to use the correct formatting for your docstrings for them to be properly recognized.
+
+## Tests
+
+-   The Dash team uses integration tests extensively, and we highly encourage you to write tests for the main functionality of your component. In the `tests` folder of the boilerplate, you can see a sample integration test. By launching it, you will run a sample Dash app in a browser. You can run the test with:
+    ```
+    python -m tests.test_render
+    ```
+    [Browse the Dash component code on GitHub for more examples of testing.](https://github.com/plotly/dash-core-components)
+
+## Ready to publish? Final scan
+
+-   Take a last look at the external resources that your component is using. Are all the external resources used [referenced in `MANIFEST.in`](https://github.com/plotly/dash-docs/blob/0b2fd8f892db720a7f3dc1c404b4cff464b5f8d4/tutorial/plugins.py#L55)?
+
+-   You're ready to publish! Continue to [step #9 here](README.md#publishing).

my_dash_component/package.json

@@ -12,7 +12,6 @@
   "author": "my-name my-email",
   "license": "my-license",
   "dependencies": {
-    "ramda": "^0.25.0",
     "react": "15.4.2",
     "react-dom": "15.4.2"
   },

package.json

@@ -14,7 +14,6 @@
   "author": "my-name my-email",
   "license": "my-license",
   "dependencies": {
-    "ramda": "^0.25.0",
     "react": "15.4.2",
     "react-dom": "15.4.2"
   },

src/demo/App.js

@@ -1,17 +1,14 @@
 /* eslint no-magic-numbers: 0 */
 import React, {Component} from 'react';
-import PropTypes from 'prop-types';
-import * as R from 'ramda';
 
 import {ExampleComponent} from '../lib';
 
 class App extends Component {
-
     constructor() {
         super();
         this.state = {
-            value: ''
-        }
+            value: '',
+        };
         this.setProps = this.setProps.bind(this);
     }
 
@@ -22,12 +19,9 @@ class App extends Component {
     render() {
         return (
             <div>
-                <ExampleComponent
-                    setProps={this.setProps}
-                    {...this.state}
-                />
+                <ExampleComponent setProps={this.setProps} {...this.state} />
             </div>
-        )
+        );
     }
 }