Skip to content

Latest commit

 

History

History
87 lines (61 loc) · 5.6 KB

Style-Guide.md

File metadata and controls

87 lines (61 loc) · 5.6 KB
Raw

This page contains guidelines for writing PureScript libraries. You might consider this a set of best practices, or if you would like to contribute to the core libraries, a set of guidelines for getting your pull requests accepted.

The PureScript core libraries are good examples of how to put these guidelines into practice.

Build Tools

  • Consider using a one-step build tool such as Pulp or gulp-purescript to make your build as simple as possible for end-users.
  • Document build steps for compilation, testing and documentation clearly in your README file.

Documentation

  • Try to document every exported type and function.
  • Even if a function seems "self-explanatory", it is still better to include a small comment or example to help beginners.
  • Short examples go a long way. Try to distill the essence of your function or type into a few lines and include it in your documentation as a Markdown code block.

It was previously common to include Markdown documentation generated by psc-docs in the repository. However, now that we have Pursuit, there is no need to do this. The recommended approach is to link to your documentation on Pursuit from your README, and to avoid checking in Markdown documentation generated by psc-docs.

Tests

  • Include tests with your project, so that contributors can easily verify their changes.
  • PureScript has several excellent testing libraries, which you can take advantage of: TODO: link to Recommended Libraries

Examples

  • Write at least one example, which might be a part of your test suite, to document how your library might be used to solve some simple complete use-case.
  • Link clearly to an example from your README file.
  • Make it obvious how to run your example.
  • If your example produces output, consider including the output (either as a code comment or in the README)

Continuous Integration

  • Set up continuous integration for your project to verify that your library compiles correctly.

  • Travis can be set up easily. Here is a template .travis.yml file:

    language: node_js
dist: trusty
sudo: required
node_js: 6
install:
  - npm install purescript pulp bower -g
  - bower install
script:
  - pulp build && pulp test

  • Display the Travis badge in your README file so that the build status is visible.

Publishing

  • Share your library on Bower, prefixing the name of your library with purescript- so others can find your work.
    • Bower works with git tags, but does not require any present tags to publish. Please run bower version 0.0.0 and push tags for your initial release (this prevents interim work not intended for publication from leaking on 0.0.0 libs).
    • Considering that you may need to be editing your library live as a part of the development of your main project, check out bower link (learn all about it here). This will enable you to keep the repos in sync as you work, and facilitate publishing when ready.
    • bower link can also be useful if you plan on contributing to a package needed by your project. Simply fork the repo, and link. Once you have your additional bindings, or features needed for your project working, you can contribute them back to the source repo easily with a Pull Request.
  • Share your library on Pursuit, so that developers can search your library documentation.
    • Include the Pursuit version badge in your README file, with a link to your documentation on Pursuit.

Types

  • Include type signatures for top-level declarations. Use type wildcards to infer the type if necessary.
  • Use newtype to convey additional information about primitive types where applicable (for example, consider using newtype EmailAddress instead of just String).
  • Do not misuse the type system when providing bindings via the FFI. Common abuses include forall props. { | props } (for "arbitrary records") and forall a. a -> ... (to avoid specifying exact types). PureScript has a rich set of types such as Foreign and FnX for safe interop with JavaScript, so this is never necessary. Create a new foreign data type if need be.

Modules

  • PureScript follows Haskell conventions for module namespacing. Some common top-level namespaces are:
    • Data for data structures and their functions
    • Control for control structures
    • Node for NodeJS-related functionality
  • Include a module export list in your modules.
  • Strive to keep module exports minimal.

Foreign Function Interface

  • PureScript is a new language, and has a need for high quality FFI libraries.
  • If you have already written a library that has FFI code into a native API, consider splitting it into two libraries, a barebones set of FFI bindings, and your extra functionality.

Runtime Requirements

  • NodeJS and the web browser have differences. Note any assumptions about the execution environment (Node-only, browser-only, etc.) in your README file.
  • Your FFI libraries may come with runtime dependencies (a particular library, for example). Document these clearly, along with any installation steps.

Keeping your library up to date

  • Try to keep your library up to date.
  • Consider using VersionEye. VersionEye reads your bower.json file and alerts you if your dependencies go out of date. If you have Travis up and running for CI, you can then easily test to see if those changes are breaking changes, and address them more promptly.
  • If your library has been deprecated, document that fact clearly in the README file.