D 2018-08-27T19:29:45.286 L Style\sGuide P b4adbd218e1a312620a1750f179ec0bd40c1949c3144aadbdf4b2684e4a25fc8 U joel W 2095 These are notes for my own use.

Prose

* The Local Yarn should be italicized. * The Local Yarn is emphatically not “a web site”.

Punctuation

* In a list of actions, list items should end with a period. * In a list of things, list items should not end with a period. * Place trailing commas and periods outside of quotation marks unless they are part of the quoted text. * [https://practicaltypography.com/hyphens-and-dashes.html|Em- and en-dashes], [https://practicaltypography.com/straight-and-curly-quotes.html|“smart” quotes and apostrophes], emoji, and math symbols should be stored as such in the original text source. Do not rely on [https://daringfireball.net/projects/smartypants/|smartypants-style text processing] at any step after writing to produce typographically correct punctuation.

Source files

* Header comment includes copyright notice, license information, and author contact info. * (Racket) All comments on their own line begin with ;;

Pre-commit checklist

# Run fossil changes --differ to ensure no extra files need to be added. # Run fossil diff --tk to ensure all edits are related. # If any files have been added with fossil add, ensure the makefile is up to date. # Ideally, any documentation (Scribble files) should be updated at the same time as the source code. # Make sure you’re on the correct branch.

Commit messages

* Commit messages should use the imperative voice. * Commit messages should be no more than ≈ 50 characters long. * If more explanation is needed, create a ticket and cross-reference it with the commit message. * Link a commit to a related ticket by using brackets [ ] containing at least the first 6 digits of the UUID. * Comments added to tickets in connection with a resolving check-in should describe why the change was made, not how (the code does that part already). Z 2b13e3d17a615f7d98daeb642ca3d568