From e60f55322858132012446aa8dda481ddc0690419 Mon Sep 17 00:00:00 2001 From: Austin Condiff Date: Thu, 6 Mar 2025 09:34:10 -0600 Subject: [PATCH 1/8] Create words-matter-apple-language-terminology-app-architecture-api.md --- ...nguage-terminology-app-architecture-api.md | 93 +++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md diff --git a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md new file mode 100644 index 0000000..6d95d1e --- /dev/null +++ b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md @@ -0,0 +1,93 @@ +--- +title: Words Matter: How Apple's Terminology Shapes App Architecture and API Design +description: Learn how Apple's thoughtful use of language and terminology can inform better app design, architecture decisions, API naming, and extension ecosystems. +headline: Words Matter: How Apple's Terminology Shapes App Architecture and API Design +subhead: Exploring the subtle yet powerful influence of Apple's terminology on software architecture and API design decisions. +date: 2025-03-06 +draft: true +--- + +In the journey of developing CodeEdit, one crucial realization we've had is the importance of how language influences software design. At first glance, it might seem trivial to obsess over words like "action," "command," "event," "perform," and "add," but diving deeper into Apple's deliberate usage of these terms reveals powerful insights that significantly shape how we build our application architecture, APIs, and overall user experience. + +### Action vs. Command: Understanding Apple's Deliberate Terminology + +When designing our API, we often use terms like "action" and "command" interchangeably without much thought—but Apple is extremely intentional with their choice of words. Understanding Apple's language can profoundly clarify our thinking and help us build a more consistent, intuitive system. + +Let's first clarify these terms: + +- **Action**: An action broadly describes any interaction or event initiated by the user, such as clicking a button, typing text, or selecting something from a menu. Actions describe user intention and events that change the application's state. +- **Command**: A command is a specific instruction—explicitly invoked by the user—that the application performs. Commands typically correspond directly to something selectable from the application's menus, buttons, or keyboard shortcuts. + +**Why distinguish between Actions and Commands?** + +In CodeEdit, we have multiple entry points for users to trigger functionality: + +- Menus in the menubar +- UI Buttons +- Quick Actions panel (similar to command palettes in other editors) +- Key Bindings + +Each of these entry points needs to trigger consistent and predictable behavior in our application. For example: + +- When you **choose** a menu item (Apple intentionally uses "choose" for menu selections), you invoke a command. +- When you **press** a keyboard shortcut or click a button, you similarly invoke a command. +- When a document is modified or a file opens, the application broadcasts an event to inform other components. + +By clearly separating these concepts, we ensure our APIs remain clear, scalable, and intuitive, not only for contributors building CodeEdit itself but also for future extension developers. + +**Apple's deliberate wording examples:** + +- Undo the last **action**: "Choose Edit > Undo" + (Here, an action is something that occurred—a general interaction.) +- Executing a menu **command** (a specific instruction): "Choose File > Open" + +Commands can represent actions—but not every action represents a command. For instance, typing text into an editor is an action (user-driven), but it's not a command because it doesn't explicitly trigger a predefined operation or instruction. + +### Events: Clarifying State Change Notifications + +Now, let's consider **events**, another crucial piece in our API design puzzle. An event in our architecture is simply a notification broadcasted when something occurs within the application. Events announce state changes to multiple observers. + +Unlike commands, which are imperative ("do this now"), events are declarative ("this happened"). + +For example: + +- User selects "Build" from a menu or presses a key shortcut, invoking a **command**. +- The build process begins, and CodeEdit then posts an **event** ("project.build.started") to notify multiple interested components (UI indicators, logs, analytics, or extensions) that the build is underway. +- Upon completion, another event ("project.build.completed") is posted. + +Events provide a clean separation of concerns. Commands initiate processes, and events announce the results, allowing multiple decoupled components to react accordingly. + +### The Power of Choosing Verbs: Apple's Naming Conventions + +Another insightful discovery is how Apple carefully chooses verbs in their APIs to convey precise meanings. Two particularly illustrative verbs are **perform** and **add**: + +- **perform**: Apple frequently uses "perform" when explicitly invoking a defined action or command: + - `perform(_: Selector)` from `NSObject` + - `NSApplication.perform(_:with:)` + + This informed our decision to adopt `CommandManager.perform("commandName")` for explicit command invocations. + +- **add**: Apple uses "add" consistently when registering something persistent, like observers or handlers: + - `NotificationCenter.addObserver(...)` + - `NSView.addSubview(...)` + + Therefore, we chose `CommandManager.addCommand("commandName")` to explicitly register commands. + +We also observed Apple's careful distinction among "choose," "pick," and "select": + +- **Choose**: Typically reserved for selecting menu items or explicit commands ("Choose File > New"). +- **Select**: Often used when interacting with UI elements like list items or selections in a collection ("Select the text you want to copy"). +- **Pick**: Commonly used for informal, quick decisions or interactions with simplified interfaces (e.g., color pickers, item pickers). + +This nuanced use of language provides clarity and reduces ambiguity, guiding users intuitively through interactions. + +### Conclusion: Why This Matters for CodeEdit + +While these linguistic distinctions may initially seem subtle or trivial, embracing Apple's approach brings significant benefits: + +- **API Consistency**: Clear distinctions make our APIs more intuitive and easier to learn. +- **Better Extension Experience**: Extension developers have clear guidelines for integrating seamlessly. +- **Enhanced Maintainability**: Explicit naming conventions reduce cognitive load for contributors, leading to cleaner codebases. + +By carefully examining and adopting Apple's deliberate and precise language conventions, we reinforce CodeEdit's design clarity and ensure the application remains intuitive, powerful, and enjoyable for users and developers alike. + From eed84d2d5209cbdf4fe18e8f65a7374f74628eca Mon Sep 17 00:00:00 2001 From: Austin Condiff Date: Thu, 6 Mar 2025 09:36:56 -0600 Subject: [PATCH 2/8] Add quotes to title and headline in blog. --- ...-matter-apple-language-terminology-app-architecture-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md index 6d95d1e..d430404 100644 --- a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md +++ b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md @@ -1,7 +1,7 @@ --- -title: Words Matter: How Apple's Terminology Shapes App Architecture and API Design +title: "Words Matter: How Apple's Terminology Shapes App Architecture and API Design" description: Learn how Apple's thoughtful use of language and terminology can inform better app design, architecture decisions, API naming, and extension ecosystems. -headline: Words Matter: How Apple's Terminology Shapes App Architecture and API Design +headline: "Words Matter: How Apple's Terminology Shapes App Architecture and API Design" subhead: Exploring the subtle yet powerful influence of Apple's terminology on software architecture and API design decisions. date: 2025-03-06 draft: true From 0963de3c94b81d8f5c06ba5765c73ea8ca3f3d77 Mon Sep 17 00:00:00 2001 From: Austin Condiff Date: Thu, 6 Mar 2025 10:36:36 -0600 Subject: [PATCH 3/8] Add image to blog post and update package name --- ...ds-matter-apple-language-terminology-app-architecture-api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md index d430404..f4e8c10 100644 --- a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md +++ b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md @@ -3,9 +3,11 @@ title: "Words Matter: How Apple's Terminology Shapes App Architecture and API De description: Learn how Apple's thoughtful use of language and terminology can inform better app design, architecture decisions, API naming, and extension ecosystems. headline: "Words Matter: How Apple's Terminology Shapes App Architecture and API Design" subhead: Exploring the subtle yet powerful influence of Apple's terminology on software architecture and API design decisions. +image: https://github.com/user-attachments/assets/f665dee7-0a23-42c9-b2e4-f4b9a482ab2c date: 2025-03-06 draft: true --- +Typewriter src= In the journey of developing CodeEdit, one crucial realization we've had is the importance of how language influences software design. At first glance, it might seem trivial to obsess over words like "action," "command," "event," "perform," and "add," but diving deeper into Apple's deliberate usage of these terms reveals powerful insights that significantly shape how we build our application architecture, APIs, and overall user experience. From da41d804f2c22a6234326f5042dcf7bbe8af5b90 Mon Sep 17 00:00:00 2001 From: Austin Condiff Date: Thu, 6 Mar 2025 10:37:48 -0600 Subject: [PATCH 4/8] Update package name and fix image tag --- ...ds-matter-apple-language-terminology-app-architecture-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md index f4e8c10..623e197 100644 --- a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md +++ b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md @@ -7,7 +7,7 @@ image: https://github.com/user-attachments/assets/f665dee7-0a23-42c9-b2e4-f4b9a4 date: 2025-03-06 draft: true --- -Typewriter src= +Typewriter In the journey of developing CodeEdit, one crucial realization we've had is the importance of how language influences software design. At first glance, it might seem trivial to obsess over words like "action," "command," "event," "perform," and "add," but diving deeper into Apple's deliberate usage of these terms reveals powerful insights that significantly shape how we build our application architecture, APIs, and overall user experience. From 4cf6145814956cd15a902020e471adf518410948 Mon Sep 17 00:00:00 2001 From: Austin Condiff Date: Thu, 6 Mar 2025 10:39:44 -0600 Subject: [PATCH 5/8] Update package name and publish blog post --- ...ds-matter-apple-language-terminology-app-architecture-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md index 623e197..eebfe88 100644 --- a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md +++ b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md @@ -5,8 +5,8 @@ headline: "Words Matter: How Apple's Terminology Shapes App Architecture and API subhead: Exploring the subtle yet powerful influence of Apple's terminology on software architecture and API design decisions. image: https://github.com/user-attachments/assets/f665dee7-0a23-42c9-b2e4-f4b9a482ab2c date: 2025-03-06 -draft: true --- + Typewriter In the journey of developing CodeEdit, one crucial realization we've had is the importance of how language influences software design. At first glance, it might seem trivial to obsess over words like "action," "command," "event," "perform," and "add," but diving deeper into Apple's deliberate usage of these terms reveals powerful insights that significantly shape how we build our application architecture, APIs, and overall user experience. From 3dc080a364d77ea8b13f67a149345cd688e6193c Mon Sep 17 00:00:00 2001 From: Austin Condiff Date: Thu, 6 Mar 2025 10:52:16 -0600 Subject: [PATCH 6/8] Update package name and blog formatting --- ...nguage-terminology-app-architecture-api.md | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md index eebfe88..edcd3e4 100644 --- a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md +++ b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md @@ -17,8 +17,9 @@ When designing our API, we often use terms like "action" and "command" interchan Let's first clarify these terms: -- **Action**: An action broadly describes any interaction or event initiated by the user, such as clicking a button, typing text, or selecting something from a menu. Actions describe user intention and events that change the application's state. -- **Command**: A command is a specific instruction—explicitly invoked by the user—that the application performs. Commands typically correspond directly to something selectable from the application's menus, buttons, or keyboard shortcuts. +**Action**: An action broadly describes any interaction or event initiated by the user, such as clicking a button, typing text, or selecting something from a menu. Actions describe user intention and events that change the application's state. + +**Command**: A command is a specific instruction—explicitly invoked by the user—that the application performs. Commands typically correspond directly to something selectable from the application's menus, buttons, or keyboard shortcuts. **Why distinguish between Actions and Commands?** @@ -63,23 +64,25 @@ Events provide a clean separation of concerns. Commands initiate processes, and Another insightful discovery is how Apple carefully chooses verbs in their APIs to convey precise meanings. Two particularly illustrative verbs are **perform** and **add**: -- **perform**: Apple frequently uses "perform" when explicitly invoking a defined action or command: +**Perform**: Apple frequently uses "perform" when explicitly invoking a defined action or command: - `perform(_: Selector)` from `NSObject` - `NSApplication.perform(_:with:)` This informed our decision to adopt `CommandManager.perform("commandName")` for explicit command invocations. -- **add**: Apple uses "add" consistently when registering something persistent, like observers or handlers: +**Add**: Apple uses "add" consistently when registering something persistent, like observers or handlers: - `NotificationCenter.addObserver(...)` - `NSView.addSubview(...)` - Therefore, we chose `CommandManager.addCommand("commandName")` to explicitly register commands. +Therefore, we chose `CommandManager.addCommand("commandName")` to explicitly register commands. We also observed Apple's careful distinction among "choose," "pick," and "select": -- **Choose**: Typically reserved for selecting menu items or explicit commands ("Choose File > New"). -- **Select**: Often used when interacting with UI elements like list items or selections in a collection ("Select the text you want to copy"). -- **Pick**: Commonly used for informal, quick decisions or interactions with simplified interfaces (e.g., color pickers, item pickers). +**Choose**: Typically reserved for selecting menu items or explicit commands ("Choose File > New"). + +**Select**: Often used when interacting with UI elements like list items or selections in a collection ("Select the text you want to copy"). + +**Pick**: Commonly used for informal, quick decisions or interactions with simplified interfaces (e.g., color pickers, item pickers). This nuanced use of language provides clarity and reduces ambiguity, guiding users intuitively through interactions. @@ -92,4 +95,3 @@ While these linguistic distinctions may initially seem subtle or trivial, embrac - **Enhanced Maintainability**: Explicit naming conventions reduce cognitive load for contributors, leading to cleaner codebases. By carefully examining and adopting Apple's deliberate and precise language conventions, we reinforce CodeEdit's design clarity and ensure the application remains intuitive, powerful, and enjoyable for users and developers alike. - From 313897b6a5258b7498e7f16d51ac64d83c0296f0 Mon Sep 17 00:00:00 2001 From: Austin Condiff Date: Thu, 6 Mar 2025 10:59:15 -0600 Subject: [PATCH 7/8] Update package name and blog conclusion. --- ...atter-apple-language-terminology-app-architecture-api.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md index edcd3e4..6cddaad 100644 --- a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md +++ b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md @@ -88,10 +88,6 @@ This nuanced use of language provides clarity and reduces ambiguity, guiding use ### Conclusion: Why This Matters for CodeEdit -While these linguistic distinctions may initially seem subtle or trivial, embracing Apple's approach brings significant benefits: - -- **API Consistency**: Clear distinctions make our APIs more intuitive and easier to learn. -- **Better Extension Experience**: Extension developers have clear guidelines for integrating seamlessly. -- **Enhanced Maintainability**: Explicit naming conventions reduce cognitive load for contributors, leading to cleaner codebases. +While these linguistic distinctions may initially seem subtle or trivial, embracing Apple's intentional approach significantly benefits our project by ensuring greater API consistency, making them more intuitive and easier to learn. It also provides extension developers with clear guidelines, enabling them to integrate seamlessly into the ecosystem. Additionally, explicit naming conventions enhance maintainability by reducing cognitive load for contributors, resulting in a cleaner and more maintainable codebase. By carefully examining and adopting Apple's deliberate and precise language conventions, we reinforce CodeEdit's design clarity and ensure the application remains intuitive, powerful, and enjoyable for users and developers alike. From ed638751fb330b1ad320ed6e61b16423e3e533c2 Mon Sep 17 00:00:00 2001 From: Austin Condiff Date: Thu, 6 Mar 2025 11:16:03 -0600 Subject: [PATCH 8/8] Update package name and blog image URL --- ...-matter-apple-language-terminology-app-architecture-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md index 6cddaad..b3b2082 100644 --- a/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md +++ b/data/blog/2025/03/words-matter-apple-language-terminology-app-architecture-api.md @@ -3,11 +3,11 @@ title: "Words Matter: How Apple's Terminology Shapes App Architecture and API De description: Learn how Apple's thoughtful use of language and terminology can inform better app design, architecture decisions, API naming, and extension ecosystems. headline: "Words Matter: How Apple's Terminology Shapes App Architecture and API Design" subhead: Exploring the subtle yet powerful influence of Apple's terminology on software architecture and API design decisions. -image: https://github.com/user-attachments/assets/f665dee7-0a23-42c9-b2e4-f4b9a482ab2c +image: https://github.com/user-attachments/assets/b0cba14c-7b1a-4f4e-8436-58e8dd77be22 date: 2025-03-06 --- -Typewriter +Typewriter In the journey of developing CodeEdit, one crucial realization we've had is the importance of how language influences software design. At first glance, it might seem trivial to obsess over words like "action," "command," "event," "perform," and "add," but diving deeper into Apple's deliberate usage of these terms reveals powerful insights that significantly shape how we build our application architecture, APIs, and overall user experience.