Coding Style

Our best-practices and guidelines include:

• Hardened JS aka Jessie
  • Arrow Function Style
• OCap Discipline
• Modules and packages: Rules for import specifiers (import ... from './x.js';) in in our RESM to NESM transition
• unit testing: yarn test
• whitespace etc.: yarn lint
  • Our eslint-config is based on Airbnb JavaScript Style
  • adding globals
• Change Logs and Release Notes
  Each package may use one of two styles:
  • CHANGELOG.md is auto-generated from Conventional commits
  • NEWS.md is manual
• Version control with git
  • commit messages: Conventional Commits
  • Tidy Commit History

See also: issues labelled code-style.

vs-code eslint plugin flakiness

where to put this? under eslint, vs-code, or other?

symptoms:

[Error - 11:42:15 AM] ESLint stack trace:
[Error - 11:42:15 AM] Error: Failed to load config "@endo" to extend from.

treatment: restart the eslint plug-in:

• Command palette (Ctrl + P), "Developer: reload window", or
• quit and restart vs-code

background: #3355

todo

• emphasize Jessie; e.g. objects-as-closures over class
  • identify code not intended to be written in Jessie (@erights Jun 8)
• static type checking with typescript and JSDoc: properjs
  • handling / avoiding "ambient" types
  • adding globals
  • use unknown rather than any in type declarations (or document justification for any) SES-shim/issues/600
• CONTRIBUTING.md : move to or cite from
• github PR template : move / copy to or cite from
• care with interleaving points: "The hazard is that, when both writing and reading a program, especially when reading other people's programs, an explicit await is not salient enough for people to understand that there's a turn boundary there, and that arbitrary turns interleave at that point, invalidating stateful assumptions." -- erights Apr 2020
• exceptions are not for flow control (or "errors are not normal API" or something like that)