From d67f4ba35caca00ad0f4f17dc2734ffdfe19f42a Mon Sep 17 00:00:00 2001 From: osy <50960678+osy@users.noreply.github.com> Date: Sat, 19 Sep 2026 10:48:32 -0500 Subject: [PATCH] docs: add comment style guideline --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 542bd147..6b8c8181 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,9 @@ We use Swift Concurrency extensively and adopt the async variants of APIs where When committing changes use the title "component: short description" where "component" is the main component you are modifying. Make sure to detail in the commit the reasoning for the change and reference the bug that you are trying to resolve. +### Comment Style +Comments are used to provide a high level summary of subsequent code or to document a design decision that is not obvious from the code. Avoid over-commenting which can pollute the code base. If you are writing more lines of comment than code, see if the comments can be simplified. Avoid: narrative comment that describes a development or debug process that led to the code being written. Avoid: adding a comment after removing code to "justify" the code that was removed. Avoid: any comment that refers to AI session internal jargon, identifiers, or progress tracking. Avoid: making similar comments in multiple places (for example making the same comment in both the header and source file). + ## Design Philosophy - Prefer simplicity over options: it can be intimating to see a wall of options when using a program for the first time. When you are tempted to add a new setting, option, configuration, or anything that requires user input ask the following question: will the majority of users need to touch this option? If the answer is no, consider choosing a safe default, putting it somewhere that is not immediately visible (e.g. menu bar or scripting interface), or even not implementing the feature at all. Avoid prompting the user for a choice unless absolutely needed. - Avoid jargon, acronyms, and technical terms: things should be as clear as possible for most users. You can assume the user has basic technical knowledge but may not know what "JIT" means or why they should choose "Vulkan" over "OpenGL." On macOS you can use the .hint() qualifier to show tooltips to explain a field or control, but do not overly rely on this. Be descriptive: "SATA Drive" is preferred over just "SATA". Do not assume the technology name is known to the user: e.g. "GPU Acceleration" is preferred over "Venus Support". Since we are on Apple platforms, we also use Apple marketing terms over the technology name when possible: e.g. "Retina" over "HiDPI" and "Apple Silicon" over ARM64 (when referring to the host machine).