Skip to content

VexFlow Coding Style

Ron B. Yeh edited this page Mar 28, 2022 · 11 revisions

Principles

  • Code must be readable.
  • Code must be testable.
  • In general, try to stick with the conventions in the existing code. (VexFlow is over a decade old, and there's a mix of styles in the code.)

Preferred Style

  • No hard-tabs. Use 2 spaces.
  • Comments get preprocessed through TypeDoc. This allows Markdown in comments.
  • Take a look at src/accidentals.ts for commenting boilerplate.
    • In particular, note the header at the top of the file.
    • If you contributed significantly to the file, feel free to add an "Author:" comment below the copyright.
    • All methods and parameters must be documented using TSDoc.
    • Run grunt typedoc to regenerate the documentation in docs/.
    • Take a look at docs/api/classes/Accidental.html for an example of a generated document.
  • Respect API boundaries. If you don't want your code to break, don't reach into its internals. E.g., prefer note.getStave() to note.stave.
  • Create a reference from master git checkout master and npm run reference
  • Run npm run test:reference on your branch before sending in a pull request.

Preferred Abbreviations

In general, avoid abbreviations like the plague. Music already has ill-defined semantics and abbreviations only further obfuscate meaning. But here are some exceptions to avoid being verbose (where appropriate):

  • accidental -> accid
    • Avoid acc because such an abbreviation could also refer to an accent
  • articulation -> artic
  • bounding box -> bbox

New Files

If you're writing code that requires a new file, e.g., a new element, class, modifier, etc.

  • Create the .ts file in src/ and a reference in src/index.ts
  • Add a test file to tests/ and a reference in tests/run.ts
    • Add YourTest.Start() to tests/run.ts
    • If your file was called slurs.ts the test file should be slurs_test.ts.
  • Run grunt to lint, build, and generate docs, and visually inspect the docs to verify correctness.
  • Also run the Visual Regression Tests and verify that there are no unexpected regressions.
Clone this wiki locally