-
Notifications
You must be signed in to change notification settings - Fork 662
VexFlow Coding Style
Ron B. Yeh edited this page Mar 28, 2022
·
11 revisions
- 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.)
- 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 indocs/
. - 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()
tonote.stave
. - Create a reference from master
git checkout master
andnpm run reference
- Run
npm run test:reference
on your branch before sending in a pull request.
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 anaccent
- Avoid
-
articulation
->artic
-
bounding box
->bbox
If you're writing code that requires a new file, e.g., a new element, class, modifier, etc.
- Create the
.ts
file insrc/
and a reference insrc/index.ts
- Add a test file to
tests/
and a reference intests/run.ts
- Add
YourTest.Start()
totests/run.ts
- If your file was called
slurs.ts
the test file should beslurs_test.ts
.
- Add
- 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.
[ VexFlow.com ] [ API ] [ GitHub Repo ] [ Contributors ]