Contracts Cleanup #25

sean-parent · 2025-09-09T23:39:08Z

Fixed spelling, math expressions (added ketex - see README), made indentation more consistent, removed non-ascii characters in favor of entities, and changed links to markdown format so they can be clicked in the generated docs.

Note

Add math rendering and doc polish

Configure KaTeX: add mdbook-katex install steps (Windows/macOS/Linux) in README.md and better-code/README.md; enable [preprocessor.katex] in better-code/book.toml
Convert Hoare logic and related formulas to LaTeX math in chapter-2-contracts.md; clarify wording (determinism/transitivity, complexity notes), and fix typos/phrasing
Normalize formatting: add code fence languages, replace non-ASCII punctuation with HTML entities, tweak links to markdown/angle-bracket form, and minor indentation/spacing fixes
Dev ergonomics: update .vscode/settings.json with custom dictionary words

^{Written by Cursor Bugbot for commit afd0b3d. This will update automatically on new commits. Configure here.}

Made a pass fixing spelling, math expressions (added ketex - see README), made indentation more consistent, removed non-ascii characters in favor of entities, and changed links to markdown format so they can be clicked in the generated docs.

This reverts commit 325cfef.

dabrahams

A lot of valuable cleanups (many of which I should have handled myself). Some things to discuss.

dabrahams · 2025-09-15T22:51:23Z

better-code/src/chapter-2-contracts.md

 Hoare used this notation, called a “Hoare triple,”

-> {P}S{Q}
+> $\{P\}S\{Q\}$


This is objectively harder to read, but as I said I'm OK with changes like this because the math will be formatted better. That said, the use of > was a “I'm doing my best with plain Markdown”-ism. Is there a more appropriate way to set this equation off? I guess “it's a quotation” still applies here…

Note also the curlies are missing from the GitHub preview of this file in all the places surrounded by $…$ . I don't know if they show up when rendered by mdbook…

I spent some time experimenting with this to find a solution that both works in mdbook katex and with GitHub Markdown. It isn't pretty. (Push shortly).

As I tried to suggest elsewhere, maybe we should be postponing any “isn't pretty” changes in favor of whatever makes writing fastest and easiest to understand when reviewing. I agree we should be using LaTeX or some similar syntax for math eventually. I just am not convinced it's a good use of time at this point to spend time changing something N² into some more complex form, especially if it won't easily render everywhere correctly.

dabrahams · 2025-09-15T22:58:52Z

better-code/src/chapter-2-contracts.md

+which is an assertion that if **precondition** $P$ is met, operation
+$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. -->


I agree in principle, and I even tried to do that, but when I looked at the preview the many transitions between gray and white backgrounds wasn't great. I realize that can be fixed with a stylesheet… but also, I think the Markdown processor forced me to add space next to the backticks that made the thing read differently from Hoare's notation. And that certainly is the case with your version. If the argument for math notation is that it's going to be easier to read, I don't think we're winning (yet).

It possibly might be better to get the book written and then take a holistic approach to math. It might be that we want to convert the entire thing to LaTeX, for example. Just a thought. More generally, let's make sure we account for the engineering tradeoffs in our approach.

@sean-parent WDYT?

I don't think we'll have much math, so I'm inclined for now to do what reads well in with mdbook-katex and bend it to also work in githhub markdown. But it is verbose -

Running mdbook is hard to preview - setup instructions in the ReadMe.

Right, it's messy and friction-inducing. Why do this now?

dabrahams · 2025-09-15T23:03:54Z

better-code/src/chapter-2-contracts.md

 is this *sequencing rule*:

-> {P}S{Q} ∧ {Q}T{R} ⇒ {P}S;T{R}
+> $\{P\}S\{Q\} \wedge \{Q\}T\{R\} \Rightarrow \{P\}S;T\{R\}$


We definitely want good math output for final production, but for the purposes of just reading and reviewing the text and changes, I really don't like the engineering cost I can't easily verify that it means what I originally wrote (and as noted elsewhere GitHub doesn't render the curlies so can't verify that way).

Fixed the curlies here too (push pending) - but verbose.

better-code/src/chapter-2-contracts.md

dabrahams · 2025-09-15T23:18:24Z

better-code/src/chapter-2-contracts.md

 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. -->


I think you may have some valid points here but too many complaints and a little to diffuse to deal with here; let's chat in person.

I do think "deterministic" is a better word than "stable".

better-code/src/chapter-2-contracts.md

dabrahams · 2025-09-15T23:26:39Z

better-code/src/chapter-2-contracts.md

-/// - Precondition: `areInIncreasingOrder` is [a strict weak
-///   ordering](https://simple.wikipedia.org/wiki/Strict_weak_ordering)
-///   over the elements of `self`.
+  /// - Precondition: `areInIncreasingOrder` is [a strict weak


What's the rationale for these spaces? I don't see how they're helpful. Personally I think they look quite awkward in the rendered output.

This matches the indentation in the source location.

OK, it's consistent with the rest of the chapter (except for the several(!) code blocks where indentation is totally messed up). But maybe we should reconsider and strip the leading indentation from code blocks. Horizontal space is at a premium in print books (do we still believe in those?) and anyway to my eye, isolated indentation looks weird on a gray backgound and does nothing useful on a white background.

dabrahams · 2025-09-24T16:25:51Z

@sean-parent ping.

dabrahams · 2025-10-16T15:52:59Z

@sean-parent I'd like to resolve this PR somehow

Co-authored-by: Dave Abrahams <dabrahams@adobe.com>

…lab/better-code into sean-parent/contracts-cleanup

cursor · 2025-10-21T23:53:54Z

better-code/src/chapter-2-contracts.md

 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. -->


Bug: Private Note Leaks in Documentation

An internal development note from "SRP" was accidentally committed as an HTML comment. This private commentary is visible in the documentation and should not be present.

dabrahams · 2025-10-27T20:42:32Z

better-code/src/chapter-2-contracts.md

-Similar rules apply to the contracts for protocol conformances: a
+Similar rules apply to the contracts for protocol conformance: a
 method satisfying a protocol requirement can have weaker preconditions
 and/or stronger postconditions than required by the protocol:


Just noticed we have two colons in this sentence!

dabrahams · 2025-10-27T20:45:40Z

better-code/src/chapter-2-contracts.md

 ## Polymorphism and Higher-Order Functions

-Similar rules apply to the contracts for protocol conformances: a
+Similar rules apply to the contracts for protocol conformance: a


This was intentionally a plural noun. I meant the entities: “protocol conformances” is like “classes”. Does it works as a singular? It no longer refers to entities that way.

sean-parent added 3 commits September 9, 2025 16:32

Some general cleanup and math support

81ac1ea

Made a pass fixing spelling, math expressions (added ketex - see README), made indentation more consistent, removed non-ascii characters in favor of entities, and changed links to markdown format so they can be clicked in the generated docs.

Removing unnessary math.

95b5862

Consistent spacing.

c21f987

sean-parent requested a review from dabrahams September 9, 2025 23:39

sean-parent added 3 commits September 9, 2025 16:43

Github markdown wants explicit braces if unbalanced.

325cfef

Revert "Github markdown wants explicit braces if unbalanced."

5bdfb41

This reverts commit 325cfef.

Attempt 2 to find compatible syntax for braces.

742f969

dabrahams reviewed Sep 15, 2025

View reviewed changes

dabrahams added 2 commits October 16, 2025 08:51

stable=>deterministic, fix cost bound

a5e50d3

stable=>deterministic

249e7f9

sean-parent and others added 4 commits October 21, 2025 15:16

Merge branch 'main' into sean-parent/contracts-cleanup

674f911

Update better-code/src/chapter-2-contracts.md

be5a2f5

Co-authored-by: Dave Abrahams <dabrahams@adobe.com>

Updating readme with katex instructions and addressing PR issues.

2bde265

Merge branch 'sean-parent/contracts-cleanup' of https://github.com/st…

5f0511d

…lab/better-code into sean-parent/contracts-cleanup

cursor bot reviewed Oct 21, 2025

View reviewed changes

dabrahams reviewed Oct 27, 2025

View reviewed changes

sean-parent added 3 commits December 22, 2025 16:11

Merge branch 'main' into sean-parent/contracts-cleanup

1faeaa3

Updating katex - cleans up some of the math.

00ce559

Reverting braces - github doesn't like it.

afd0b3d

Contracts Cleanup #25

Are you sure you want to change the base?

Contracts Cleanup #25

Uh oh!

Conversation

sean-parent commented Sep 9, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dabrahams left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dabrahams Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dabrahams commented Sep 24, 2025

Uh oh!

dabrahams commented Oct 16, 2025

Uh oh!

cursor bot Oct 21, 2025

Choose a reason for hiding this comment

Bug: Private Note Leaks in Documentation

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sean-parent commented Sep 9, 2025 •

edited by cursor bot

Loading

dabrahams Oct 25, 2025 •

edited

Loading