File size: 3,068 Bytes
5fae594 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 |
# Contributing to bluebird
1. [Directory structure](#directory-structure)
2. [Style guide](#style-guide)
3. [Scripts and macros](#scripts-and-macros)
4. [JSHint](#jshint)
5. [Testing](#testing)
## Directory structure
- `/benchmark` contains benchmark scripts and stats of benchmarks
- `/browser` contains scripts and output for browser testing environment
- `/js` contains automatically generated build output. **NOTE** never commit any changes to these files to git.
- `/js/browser` contains a file suitable for use in browsers
- `/js/main` contains the main build to be used with node. The npm package points to /js/main/bluebird.js
- `/js/debug` contains the debug build to be used with node. Used when running tests
- `/js/zalgo` contains the zalgo build not to be used by any mortals.
- `/node_modules` contains development dependencies such as grunt
- `/src` contains the source code
- `/test/mocha` contains tests using the mocha testing framework
## Scripts and macros
Scripts and macros are necessary for the code the code to remain readable and performant. For example, there is no way to turn the `arguments` object into an array without using a build step macro unless you want to compromise readability or performance.
`/ast_passes.js` contains functions called ast passes that will parse input source code into an AST, modify it in some way and spit out new source code with the changes reflected.
`/src/constants.js` contains declarations for constants that will be inlined in the resulting code during in the build step. JavaScript lacks a way to express constants, particularly if you are expecting the performance implications.
`/Gruntfile.js` contains task definitions to be used with the Grunt build framework. It for example sets up source code transformations.
`/bench` a bash script to run benchmarks.
`/mocharun.js` a hack script to make mocha work when running multiple tests in parallel processes
## JSHint
Due to JSHint globals being dynamic, the JSHint rules are declared in `/Gruntfile.js`.
## Style guide
Use the same style as is used in the surrounding code.
###Whitespace
- No more than 80 columns per line
- 4 space indentation
- No trailing whitespace
- LF at end of files
- Curly braces can be left out of single statement `if/else/else if`s when it is obvious there will never be multiple statements such as null check at the top of a function for an early return.
- Add an additional new line between logical sections of code.
###Variables
- Use multiple `var` statements instead of a single one with comma separator. Do not declare variables until you need them.
###Equality and type checks
- Always use `===` except when checking for null or undefined. To check for null or undefined, use `x == null`.
- For checks that can be done with `typeof`: do not make helper functions, save results of `typeof` to a variable or make the type string a non-constant. Always write the check in the form `typeof expression === "constant string"` even if it feels like repeating yourself.
## Testing
|