Always prefer newer swift features and idioms, such as #Preview instead of PreviewProvider, and @Previewable if you need @State within the #Preview. Use @Observable instead of the older @ObservableObject.
Code should always optimize for clarity, readability, and most of all, simplicity. Pause when requirements are ambiguous and ask a brief clarifying question rather than guessing and over-building. If the code you are writing is complex, rethink the solution to find a simpler path unless optimization or high performance was specifically requested.
Write code that reads like a narrative: names should do most of the explaining, control flow should be simple, and "clever" should lose to "obvious" every time. Prefer small, single-purpose functions with clear inputs/outputs over long methods with mixed responsibilities. Keep state minimal and intentional: every stored property should earn its keep, and if it exists it should be clear what invariant it represents (what must always be true about it). When something is subtle, make that subtlety explicit with structure (guards, early returns, helper methods) so the reader doesn’t have to simulate the program in their head.
Do not commit your work automatically, but provide a commit message at the end of your work. It should start with a brief overview (max 90 chars), followed by bullet point descriptions of the major work completed since the last commit.
Comments should add information that the code can't. Good comments capture intent, constraints, consequences and references using plain english without jargon. Use comments to explain why the code is necessary, how the code works, why it exists, what would break without it, and what assumptions must hold. Inline comments only at the exact point where a reader would otherwise say "wait, why are we doing that?", and include the reasoning ("We do this at X, because otherwise Y..."). When in doubt, prefer more explanation over less, and write comments so clearly and concretely that even a non-technical reader could follow the intent and mechanics.
If an algorithm is developed (or formerly simple code becomes more complex or algorithmic), the high-level steps the algorithm takes should be documented in the function's docstrings clearly and simply.
Objects must always include documentation comments (///) with parameter callouts for all public methods and properties. Documentation comments describing the top-level object should be written in full sentences with proper grammar. Wherever possible include usage examples showing input and output for functions where the output is not obvious or not discrete.
All comments should be wrapped at 90 characters. If a comment wraps for only a word or two, either attempt to shorten it to a single line, or when that reduces clarity, expand to fill the the next line. Regular comments // should be less formal starting with a lowercase letter, and not ending in a period.
Swift Tests are run using swift test and use the newer swift-testing framework which is now built into swift, and does not require any additional packages. Tests are written in a BDD style using @Suite to provide Context/When clauses and @Test for Should statements. The top level @Suite is the Test's file name, followed by the various features/methods supported by the file being tested. Each file being tested in the Repo should have its own file in the Tests directory mirroring the directory structure. Do not increase verbosity and use more @Suites than is necessary.
Example of a verbose test suite for a Music package that provides the capability to identify chords based on a set of pitches and optional Key. In this example, the additional @Suites were necessary as the test suites were very large and the logic quite complex.
@Suite("HarteSyntax Tests")
struct HarteSyntaxTests {
@Suite("Feature: Chord Identification")
struct ChordIdentification {
@Suite("Given a set of pitches")
struct GivenAPitchSet {
@Suite("When a key is provided")
struct WhenAKeyIsProvided {
@Test("It should prioritize chords within the key")
func prioritizeChordsWithinKey () {
// ...
}
}
}
}
}A Simpler version for a simpler package or file might be:
@Suite("HarteDegree Tests")
struct HarteShorthandTests {
@Suite("When initializing")
struct NormalizedTests {
@Test("It should parse plain degrees with accidentals")
func parsesDegreesAndAccidentals () throws {
// ...
}
@Test("It should trim whitespace")
func trimsWhitespace() throws {
// ...
}
}
}