Refine contracts chapter and update config files#37
Open
sean-parent wants to merge 1 commit intomainfrom
Open
Conversation
Improves clarity and consistency in 'chapter-2-contracts.md' by revising explanations, updating code examples, and correcting terminology. Adds custom dictionary words to VSCode settings and enables the Katex preprocessor in book.toml for better math rendering.
Closed
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
dabrahams
reviewed
Jan 7, 2026
| *S* establishes **postcondition** *Q*. | ||
|
|
||
| <!-- This had been using math for pre and post conditions, but I find mixing math and code makes it look like we are talking about different `x` and $x$ variables and equality vs. assignment gets confusing. I think if the operation is expressed in code, the conditions should be expressed in code. --> | ||
|
|
Collaborator
There was a problem hiding this comment.
But, Sean, that is just not possible in general, as we say repeatedly. You can't express “is a total preorder” in code, at least not reasonably.
Collaborator
There was a problem hiding this comment.
Also, I don't see you making the adjustment this comment is referring to. Did you review these diffs before requesting another review?
dabrahams
reviewed
Jan 7, 2026
| explicit precondition that isn't implied by the summary: it requires | ||
| that the predicate be a strict weak ordering. | ||
|
|
||
| <!-- SRP: this section bothers me. "among others" instead of fully spelling out the requirements, using (i, j + 1) which may not exist, and the n^2 comparisons without calling out the O(n^3) complexity or which properties could be practically checked. Also is "stable" the term we want to use? Regular and deterministic are also candidates. I've tried to rewrite this a couple of times, but it just gets too complex and the main point is lost. --> |
Collaborator
There was a problem hiding this comment.
The “stable” problem is resolved. If you still don't like the way it's written I wish you'd propose actual edits rather than leave a remark like this in the file which I suspect can never be resolved, because the prose that addresses these concerns is worse.
dabrahams
reviewed
Jan 7, 2026
| is this *sequencing rule*: | ||
|
|
||
| > {P}S{Q} ∧ {Q}T{R} ⇒ {P}S;T{R} | ||
| > {P}S{Q} ^ {Q}T{R} => {P}S;T{R} |
Collaborator
There was a problem hiding this comment.
Why is this one change an improvement?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Improves clarity and consistency in 'chapter-2-contracts.md' by revising explanations, updating code examples, and correcting terminology. Adds custom dictionary words to VSCode settings and enables the Katex preprocessor in book.toml for better math rendering.
This salvages the changes from PR #25 without moving to latex and html entities for math and non-ascii symbols. I did not (yet) remove all non-ascii symbols.
Note
Improves clarity, consistency, and formatting in
better-code/src/chapter-2-contracts.md(e.g., prefer code over math for conditions, adjust wording/terminology like deterministic, fix phrasing, normalize doc comment/code fences, addswiftfencing) while keeping examples aligned with the narrative.[preprocessor.katex]inbetter-code/book.toml.vscode/settings.jsonwith customcSpell.wordsand retains wrapping settingsWritten by Cursor Bugbot for commit a0368e3. This will update automatically on new commits. Configure here.