D 2019-04-18T03:08:05.601
L Style\sGuide
P 2f5ce2a9231e2fef0986b77d796ba11ca5d20056e6599fd3abc0d81014f77991
U joel
W 2327
These are notes for my own use.
<h2>Prose</h2>
* <i>The Local Yarn</i> should be italicized.
* <i>The Local Yarn</i> is emphatically not “a web site”.
<h2>Punctuation</h2>
* In a list of <em>actions</em>, list items should end with a period.
* In a list of <em>things</em>, 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.
<h2>Source files</h2>
* 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 <code>;;</code>
<h2>Pre-commit checklist</h2>
# Run <code>fossil changes --differ</code> to ensure no extra files need to be added.
# Run <code>fossil diff --tk</code> to ensure all edits are related.
# If any files have been added with <code>fossil add</code>, 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 <code>.scrbl</code> files have changed, run <code>make scribble</code> to ensure the documentation compiles and is published to this repo.
# Make sure you’re on the correct branch.
<h2>Commit messages</h2>
* 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 <code>[ ]</code> containing at least the first 6 digits of the UUID.
* Comments added to tickets in connection with a resolving check-in should describe <em>why</em> the change was made, not <em>how</em> (the code does that part already).
Z e8b80b5c0bd038ee64f123ce62e4994c
