|Page Name:||Style Guide|
These are notes for my own use.
- The Local Yarn should be italicized.
- The Local Yarn is emphatically not “a web site”.
- 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.
- Em- and en-dashes, “smart” quotes and apostrophes, emoji, and math symbols should be stored as such in the original text source. Do not rely on smartypants-style text processing at any step after writing to produce typographically correct punctuation.
- Header comment includes copyright notice, license information, and author contact info.
- Lines should be hard-wrapped at ≈100 characters. This includes prose sources.
- (Racket) All comments on their own line begin with
fossil changes --differto ensure no extra files need to be added.
fossil diff --tkto 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. If any
.scrblfiles have changed, run
make scribbleto ensure the documentation compiles and is published to this repo.
- Make sure you’re on the correct branch.
- 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).