Foundations of API Design chapter #2994

tall-vase · 2025-12-05T13:29:11Z

Includes most of chapter 1 of foundations of API Design for Idiomatic Rust. Brought in from the gdoc. Tests have not been run locally yet, formatting has.

gribozavr · 2025-12-05T14:21:59Z

src/idiomatic/foundations-api-design/clarity-readability.md is being added, but it is empty and it is not linked from SUMMARY.md. Delete it?

(GitHub does not allow me to leave a comment on an empty file)

src/idiomatic/foundations-api-design.md

src/idiomatic/foundations-api-design/meaningful-doc-comments.md

src/idiomatic/foundations-api-design/meaningful-doc-comments/avoid-redundancy.md

gribozavr · 2025-12-05T14:34:11Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/avoid-redundancy.md

+```
+
+<details>
+- Motivation: Documentation that repeats name/signature information provides nothing new to the API user.


Suggested change

- Motivation: Documentation that repeats name/signature information provides nothing new to the API user.

- Motivation: Documentation that merely repeats name/signature information provides nothing new to the API user.

gribozavr · 2025-12-05T20:53:16Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/who-are-you-writing-for.md

+```
+
+<details>
+- Motivation: It can be easy to fall into a pattern of writing only for you, but most documentation is for people coming in with a different perspective.


Suggested change

- Motivation: It can be easy to fall into a pattern of writing only for you, but most documentation is for people coming in with a different perspective.

- Background: The [curse of knowledge](https://en.wikipedia.org/wiki/Curse_of_knowledge) is a cognitive bias where experts assume that others have the same level of expertise and perspective.

- Motivation: Your reader does not have the same level of expertise and the same perspective as you. Don't write for people like yourself, write for others.

gribozavr · 2025-12-05T20:54:12Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/who-are-you-writing-for.md

+
+```rust
+// TODO: What's a good illustration here?
+```


// expert writes for experts /// Canonicalizes the MIR for the borrow checker. /// /// This pass ensures that all borrows conform to the NLL-Polonius constraints /// before we proceed to MIR-to-LLVM-IR translation. pub fn canonicalize_mir(mir: &mut Mir) { // ... } // expert writes for newcomers /// Prepares the Mid-level IR (MIR) for borrow checking. /// /// The borrow checker operates on a simplified, "canonical" form of the MIR. /// This function performs that transformation. It is a prerequisite for the /// final stages of code generation. /// /// For more about Rust's intermediate representations, see the /// [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/mir/index.html). pub fn canonicalize_mir(mir: &mut Mir) { // ... }

gribozavr · 2025-12-05T20:58:47Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/who-are-you-writing-for.md

+  much information.
+- Always ask: Is this documentation making it difficult for the API user? Are
+  they able to quickly grasp what they need or find out where they could need
+  it?


I'd also say something like "Experts also read API level documentation. Doc comments might not be the right place to educate your audience about the basics of your domain. In that case, signpost and namedrop - divert people to long-form documentation."

gribozavr · 2025-12-05T21:00:35Z

src/idiomatic/foundations-api-design/predictable-api.md

+
+# Predictable API
+
+Keep your APIs predictable through naming conventions and implementing common


Suggested change

Keep your APIs predictable through naming conventions and implementing common

Keep your APIs predictable by following naming conventions and implementing common

Parallel sentence structure.

gribozavr · 2025-12-05T21:01:02Z

src/idiomatic/foundations-api-design/predictable-api.md

+Keep your APIs predictable through naming conventions and implementing common
+traits.
+
+<!-- TODO -->


Some speaker notes would be nice. What is the framing for this section?

gribozavr

(misclick, I meant to simply "comment", but clicked "approve"; for clarity switching to "request changes")

gribozavr · 2025-12-07T00:53:13Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions.md

+# Naming Conventions
+
+<details>
+- One core component of readability and predictability is the way function names are composed.


Suggested change

- One core component of readability and predictability is the way function names are composed.

- One core component of API readability and predictability is the way function names are composed.

gribozavr · 2025-12-07T00:55:00Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions.md

+Rust's community developed naming conventions early, making them mostly
+consistent in places like the standard library.
+
+- Here we'll learn common components of rust method names, giving examples from


Suggested change

- Here we'll learn common components of rust method names, giving examples from

- In this section we'll learn common components of Rust method names, giving examples from

gribozavr · 2025-12-07T00:55:39Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions.md

+like a domain-specific language and quickly understand the functionality and use
+cases of a method.
+
+Rust's community developed naming conventions early, making them mostly


Suggested change

Rust's community developed naming conventions early, making them mostly

- Rust community developed naming conventions early, making them mostly

gribozavr · 2025-12-07T00:56:15Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions.md

+<details>
+- One core component of readability and predictability is the way function names are composed.
+
+A formal and consistently-applied naming convention lets developers treat names


Suggested change

A formal and consistently-applied naming convention lets developers treat names

- Formal and consistently-applied naming conventions let developers treat names

gribozavr · 2025-12-07T14:04:16Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/01-get.md

@@ -0,0 +1,31 @@
+---
+minutes: 2
+---


These are great slides about naming conventions, but I have a couple of comments. I have left the comments on the "get" and "push" slides, but please apply them everywhere. All slides in this section should follow the same structure.

gribozavr · 2025-12-07T17:16:24Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/13-as-and-ref.md

+<details>
+- Method for getting a reference-style value from an owned or borrowed value.
+
+- Often used for getting something internal to a type.


Suggested change

- Often used for getting something internal to a type.

- The type implementing an "as" method should contain one primary piece of data that is being borrowed out.

- The "as" naming convention does not work if the data type is an aggregate of many fields without an obvious primary one. Think about the call site:

```rust

my_vec.as_ptr() // OK

my_person.as_first_name() // does not read right, don't use "as_"

my_person.first_name() // OK

```

- If you want to have two getters that you need to distinguish, one that returns first name by value, and another one that returns it by reference, use `_ref` suffix:

```rust

impl Person {

fn first_name(&self) -> String

fn first_name_ref() -> &str

fn first_name_mut() -> &mut String

}

```

"Something internal" is quite unspecific. Here's my attempt at making it concrete. The "as" pattern is not applicable in every case, we need to have a type that wraps one specific thing that is being borrowed out.

Given the number of code examples, could you make a separate slide for this point that has all the necessary code snippets on the slide?

gribozavr · 2025-12-07T17:20:59Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/14-mini-exercise.md

+Slice::get // ?
+Slice::get_unchecked_mut // ?


Suggested change

Slice::get // ?

Slice::get_unchecked_mut // ?

slice::get // ?

slice::get_unchecked_mut // ?

gribozavr · 2025-12-07T17:21:15Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/14-mini-exercise.md

+2. What should we name these signatures?
+
+```rust,compile_fail
+// What are the types for these methods?


Suggested change

// What are the types for these methods?

// What are the types of these methods?

gribozavr · 2025-12-07T17:28:02Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/14-mini-exercise.md

+Option::is_some // ?
+Slice::get // ?
+Slice::get_unchecked_mut // ?
+Option::as_ref // ?


Suggested change

Option::as_ref // ?

Option::as_ref // ?

str::from_utf8_unchecked_mut // ?

Rc::get_mut // ?

Vec::dedup_by_key // ?

gribozavr · 2025-12-07T17:28:46Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/14-mini-exercise.md

+  types of the functions should be.
+
+- Go through the unnamed methods and brainstorm what names those methods should
+  have.


Please add expected answers to the speaker notes (for both Qs).

gribozavr · 2025-12-07T17:41:15Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/06-with.md

+PathBuf::with_extension
+PathBuf::with_file_name


These two methods are actually defined on Path (they are callable through PathBuf because PathBuf: Deref<Target=Path>)

gribozavr · 2025-12-07T17:44:17Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/08-into.md

@@ -0,0 +1,29 @@
+---
+Minutes: 2


Suggested change

Minutes: 2

minutes: 2

src/SUMMARY.md

gribozavr · 2025-12-07T17:47:13Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/12-to.md

+Prefix to a function that takes a borrowed value and creates an owned value
+
+```rust
+String::to_owned // &str -> String (&str is not consumed)


Suggested change

String::to_owned // &str -> String (&str is not consumed)

str::to_owned // &str -> String (&str is not consumed)

gribozavr · 2025-12-07T17:47:43Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/14-mini-exercise.md

+minutes: 10
+---
+
+Mini-exercise


Suggested change

Mini-exercise

# Exercise

gribozavr · 2025-12-07T17:48:00Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/14-mini-exercise.md

+minutes: 10
+---
+
+Mini-exercise


Please rename the file as well to remove "mini".

Co-authored-by: Dmitri Gribenko <gribozavr@gmail.com>

…oc comment slide

gribozavr · 2025-12-08T14:55:28Z

src/idiomatic/foundations-api-design/predictable-api/common-traits.md

+- Traits are one of the most potent tools in the Rust language. The language and ecosystem expects you to use them, and so a big part of _predictability_ is what traits are implemented for a type!
+
+- Traits should be liberally implemented on types you author, but there are
+  caveats!


For this point Google's Rust style guide also leans on the distinction between library and application code (see the definition in another comment I left previously on this PR).

Specifically, we say this:

### Add trait implementations when they become necessary As a general rule, low-level library code should anticipate users' needs proactively, while application code should add trait impls as needed.

We also provide guidance for implementing individual traits in library code, which should go into respective slides.

### Specific guidance for important traits {#important-traits} * **Types with public fields**: Consider implementing traits implemented by all subfields. * **Error types**: Implement the `Copy` trait whenever possible. `Copy` types are simpler to manage and propagate because they can be passed by value without moving ownership. An example of a case where this is not possible is if the error must contain non-`Copy` fields like a `String`. * **`Copy`**: Implement whenever it is reasonably clear that the type will continue to be `Copy` in the future. * **`Clone`**: Most types should implement `Clone` unless they represent some external resource. * **`Default`**: Implement if the type implements `new()` or otherwise has a default state. For context, see Clippy lint [`new_without_default`](https://rust-lang.github.io/rust-clippy/master/index.html#new_without_default). * **`PartialEq`** / **`Eq`**: If you want users to use the `==` operator, prefer implementing `PartialEq` over `Eq`. When you do implement `Eq`, be aware of the additionally required reflexivity (details: https://doc.rust-lang.org/std/cmp/trait.Eq.html). * **`PartialOrd`** / **`Ord`**: If you want users to use the `<` or `>` operators, prefer implementing `PartialOrd` over `Ord`. When you do implement `Ord`, be aware that it requires total ordering (details: https://doc.rust-lang.org/std/cmp/trait.Ord.html). * **Map keys** * If you think it is likely that a type will be used as a map key or otherwise cached, implement `Hash` and `Eq`. * If, in addition, the type has a clear total ordering, implement `Ord` (and any traits it needs).

gribozavr · 2025-12-08T16:35:56Z

src/idiomatic/foundations-api-design/predictable-api/common-traits/01-debug.md

+
+"Write to string" trait, for debug purposes.
+
+Derivable: ✅ When to implement: Almost always


Is it intentional that you put both of these things on the same line? (to save space?)

If yes, maybe add some space before "When" with   characters for visual separation.

(on all slides)

gribozavr · 2025-12-08T16:37:14Z

src/idiomatic/foundations-api-design/predictable-api/common-traits/02-partialeq-eq.md

+minutes: 10
+---
+
+PartialEq and Eq


Suggested change

PartialEq and Eq

# `PartialEq` and `Eq`

Please apply to all slides: ensure there is a Markdown section title element, and the trait names are typeset using code font.

gribozavr · 2025-12-08T16:38:15Z

src/idiomatic/foundations-api-design/predictable-api/common-traits/02-partialeq-eq.md

+- A type can't implement `Eq` without implementing `PartialEq`.
+
+- Reminder: Partial means "there are invalid members of this set for this
+  function."


Please use more words to explain partial equality. "invalid" is a bit abstract and unclear, if one is not already familiar with this concept.

gribozavr · 2025-12-08T16:38:51Z

src/idiomatic/foundations-api-design/predictable-api/common-traits/02-partialeq-eq.md

+  function."
+
+  This doesn't mean that equality will panic, or that it returns a result, just
+  that there may be values that may not behave as you expect equality to behave.


Please more directly say what equality laws those elements may break. I really want to hear the word "reflexivity" and a brief explanation of that.

gribozavr · 2025-12-08T16:41:12Z

src/idiomatic/foundations-api-design/predictable-api/common-traits/02-partialeq-eq.md

+  `PartialEq` exists to separate types like f32/f64 from types with Total
+  Equality.


Suggested change

`PartialEq` exists to separate types like f32/f64 from types with Total

Equality.

- Types which support only partial equality are relatively rare. Default to implementing `Eq` if you can.

- `PartialEq` exists primarily to enable floating point types (`f32` and `f64`) to support a weak form of equality comparison through a trait, while enabling most types opt into the stronger guarantees of total equality through `Eq`.

gribozavr · 2025-12-08T16:43:33Z

src/idiomatic/foundations-api-design/predictable-api/common-traits/03-partialord-ord.md

+
+Partial ordering & Total ordering.
+
+Derivable: ✅ When to implement: Almost always.


I don't really agree with the "almost always" guidance here. Many types don't have a natural order, and people should not be making up one unless it is really needed.

gribozavr · 2025-12-22T21:32:57Z

src/idiomatic/foundations-api-design/meaningful-doc-comments.md

+/// Function from A to B // ❌ Redundant
+fn a_to_b(a: A) -> B {...}
+ 
+/// Connects to the database. // ❌ Lacks detail                                                                                                                   │


Suggested change

/// Connects to the database. // ❌ Lacks detail │

/// Connects to the database. // ❌ Lacks detail │

What's up with the vertical bar?

gribozavr · 2025-12-22T21:38:44Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/library-vs-application-docs.md

+- Application code has the opposite traits: it has few users, solves a specific\
+  problem, and changes often. For application code elaborate documentation\
+  quickly becomes outdated and misleading. It is also difficult to extract a\
+  positive RoI from boilerplate docs even while they are up to date, because\


What's up with the backslashes?

Bring in existing foundations of API design work from google doc

9c1d7d1

tall-vase added the deep_dives/idiomatic label Dec 5, 2025

gribozavr approved these changes Dec 5, 2025

View reviewed changes

gribozavr requested changes Dec 5, 2025

View reviewed changes

gribozavr reviewed Dec 7, 2025

View reviewed changes

tall-vase and others added 3 commits December 9, 2025 09:54

Apply suggestions from code review / Meaningful Doc Comments

e79081e

Co-authored-by: Dmitri Gribenko <gribozavr@gmail.com>

Apply feedback to the avoid redundancy slide + add the anatomy of a d…

4a92f68

…oc comment slide

Apply feedback, expand some minor slides

75c73cf

tall-vase requested a review from gribozavr December 12, 2025 14:13

gribozavr reviewed Dec 22, 2025

View reviewed changes

	- Motivation: Documentation that repeats name/signature information provides nothing new to the API user.
	- Motivation: Documentation that merely repeats name/signature information provides nothing new to the API user.

-- Motivation: It can be easy to fall into a pattern of writing only for you, but most documentation is for people coming in with a different perspective.
+- Background: The [curse of knowledge](https://en.wikipedia.org/wiki/Curse_of_knowledge) is a cognitive bias where experts assume that others have the same level of expertise and perspective.
+- Motivation: Your reader does not have the same level of expertise and the same perspective as you. Don't write for people like yourself, write for others.


		# Predictable API

		Keep your APIs predictable through naming conventions and implementing common

	Keep your APIs predictable through naming conventions and implementing common
	Keep your APIs predictable by following naming conventions and implementing common

	- One core component of readability and predictability is the way function names are composed.
	- One core component of API readability and predictability is the way function names are composed.

	- Here we'll learn common components of rust method names, giving examples from
	- In this section we'll learn common components of Rust method names, giving examples from

	Rust's community developed naming conventions early, making them mostly
	- Rust community developed naming conventions early, making them mostly

	A formal and consistently-applied naming convention lets developers treat names
	- Formal and consistently-applied naming conventions let developers treat names

-- Often used for getting something internal to a type.
+- The type implementing an "as" method should contain one primary piece of data that is being borrowed out.
+  - The "as" naming convention does not work if the data type is an aggregate of many fields without an obvious primary one. Think about the call site:
+  ```rust
+  my_vec.as_ptr() // OK
+  my_person.as_first_name() // does not read right, don't use "as_"
+  my_person.first_name() // OK
+  ```
+  - If you want to have two getters that you need to distinguish, one that returns first name by value, and another one that returns it by reference, use `_ref` suffix:
+  ```rust
+  impl Person {
+    fn first_name(&self) -> String
+    fn first_name_ref() -> &str
+    fn first_name_mut() -> &mut String
+  }
+  ```

	// What are the types for these methods?
	// What are the types of these methods?

		PathBuf::with_extension
		PathBuf::with_file_name

-Option::as_ref // ?
+Option::as_ref // ?
+str::from_utf8_unchecked_mut // ?
+Rc::get_mut // ?
+Vec::dedup_by_key // ?

	String::to_owned // &str -> String (&str is not consumed)
	str::to_owned // &str -> String (&str is not consumed)


		"Write to string" trait, for debug purposes.

		Derivable: ✅ When to implement: Almost always

		`PartialEq` exists to separate types like f32/f64 from types with Total
		Equality.


		Partial ordering & Total ordering.

		Derivable: ✅ When to implement: Almost always.

	/// Connects to the database. // ❌ Lacks detail │
	/// Connects to the database. // ❌ Lacks detail │

Foundations of API Design chapter #2994

Are you sure you want to change the base?

Foundations of API Design chapter #2994

Uh oh!

Conversation

tall-vase commented Dec 5, 2025

Uh oh!

gribozavr commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

gribozavr 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!

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!

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!

Reviewers

Assignees

gribozavr commented Dec 5, 2025 •

edited

Loading