Skip to content

Latest commit

 

History

History
95 lines (78 loc) · 4.48 KB

CONTRIBUTING.md

File metadata and controls

95 lines (78 loc) · 4.48 KB
Raw

Contribution Guidelines

  • Feel free to open issues or pull requests
  • They may not be addressed or merged
  • You can ignore coding styles if you want
  • Readability trumps almost everything else

Coding Style

If you want to help with style, here are some rough guidelines on style ideas:

Formatting

  • Arguments to methods are snake_case
  • Regular variables are camelCase
  • Returned attributes are snake_case
  • A single line should contain max 80 characters including the newline
  • If a top level scalar would go over 80 characters in a line, that's ok
  • Don't bother with () in functions when not needed: const a = b => c
  • If there are multiple things together, alphabetize them
  • Don't split up long strings over multiple lines
  • Lines should be terminated by explicit semicolons
  • Logic like ternary operators should not extend beyond a single line
  • Don't let any lines linger when they don't do anything
  • Use single '' quotes not double "" quotes, except when `` is required
  • Avoid double specifying an attribute and value, {type: type} vs {type}
  • Always use {} with if, else, etc statements
  • Document the top of methods with what the arguments are and what is returned

White Space

  • Spaces not tabs, 2 spaces
  • Minimize function nesting, make new files if nesting is required
  • No extraneous whitespace
  • A single newline should appear at the end of a file
  • Tightly space objects, like {attribute: value} not { attribute : value }
  • If conditions should avoid spanning multiple lines

Control Flow

  • Async functions should support both cbk and Promise style
  • Use async.js methods for asynchronous control flow
  • Use async auto and returnResult for all non-event async functions
  • Try to exit early from functions when possible, and note this exit in comment
  • Prefer cbk over Promise style, aside from in tests or in Promise libs
  • Use asyncAuto for asynchronous control flow dependency management
  • Callbacks should generally be named cbk even when redefinining in inner scope
  • Avoid mixing non-async complex logic and async control flows in the same file
  • Minimize async nesting in returned attributes and in method arguments
  • Methods should always document their arguments and their output

Variables

  • Generally use undefined rather than null when defining nil types
  • Prefer variable assignments on new lines rather than on a single line
  • Reduce the usage of . property access, like isArray instead of Array.isArray
  • When there is a newline in an object, always put a comma at the end of a line
  • Short properties always go first in objects: {short, longer: type}
  • If a statement relies on a statement above it, it should have a newline above
  • Avoid including scalar values such as strings or numbers in the code itself
  • Prefer hex serialization over base64 or Buffers in arguments or output
  • Avoid any function arguments that are multiple data types

JS Features

  • Limit usage of let and never use var, prefer const
  • Limit use of npm dependencies when possible, only use good dependencies
  • Target support of the oldest node.js LTS release still being supported
  • Never use class or prototype
  • Do not import more methods from an import than you actually use
  • Try to avoid passing objects in arguments as much as possible
  • Prefer using function iteration like map and forEach over for and while
  • Use arrow functions and not function functions whenever possible
  • Functions should only take and return a single object as argument, result
  • Use the || flags to select between truthy variable options
  • Use !! to explicitly coerce non Bool variables to Boolean

Errors

  • Never ignore an error case, always deal with it as soon as possible
  • In the case of errors, do include the error string in the code
  • Add simple validations to help target simple calling mistakes
  • When throwing or returning error messages, use PascalCase for the message
  • Use HTTP status codes as a guideline: 4** is a local issue, 5** is remote
  • Return async errors as arrays: [typeNumber, errorMsgString, extraDetails]
  • Try to be very specific with error messages and try to not repeat one
  • Callbacks should always be called as (err, result)
  • Try and catch should not be used unless an error is expected

Testing

  • Ideally there is a tap unit test that has 100% coverage, using mock-lnd
  • Also good is a ln-docker-daemons integration test for common scenarios
  • Design methods so that they can easily tested with self-contained unit tests
  • Avoid breaking existing tests, changes should also change relevant tests