0Pricing
Swift Academy · Leçon

Guide de style et recommandations de conception d’API

Utilisez des noms clairs, des étiquettes d’arguments judicieuses, des valeurs par défaut pertinentes et des commentaires de documentation concis pour concevoir des API Swift agréables à utiliser.

Guide de style et recommandations de conception d’API est une leçon Swift Academy gratuite sur CoddyKit. Ceci est la leçon 2 sur 3. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage Swift Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours Swift Academy comprend 3 leçons au total.

Principes

Les bonnes API sont lisibles, prévisibles et concises.

  • Des noms qui décrivent l’intention
  • Des étiquettes d’arguments utiles
  • Des valeurs par défaut pour les cas courants
  • Une documentation et des exemples concis

Notions de base du nommage

Actions => verbes, données => noms. Évitez les abréviations qui masquent le sens.

// Prefer clear, simple names.
// BAD:
func doCalc(_ a: Int, _ b: Int) -> Int { a + b }

// GOOD:
func sum(_ a: Int, _ b: Int) -> Int { a + b }

// BAD (ambiguous):
struct Cfg { let v: Int }
// GOOD (nouns for data types):
struct Configuration { let retries: Int }

print(sum(2, 3))  // 5

Étiquettes d’arguments

Les étiquettes rendent les sites d’appel naturels à lire : remove(at:), insert(_:at:).

// Choose labels that explain a parameter's role.
// BAD:
func remove(_ index: Int) { print("remove", index) }

// BETTER:
func remove(at index: Int) { print("remove at", index) }

// Mixed labels:
func insert(_ item: String, at index: Int) {
    print("insert", item, "at", index)
}

remove(at: 2)
insert("a", at: 1)

Bonnes valeurs par défaut

Utilisez des paramètres par défaut pour raccourcir les appels courants tout en conservant la flexibilité.

// Provide defaults to cover the 80% case.
func greet(_ name: String, times: Int = 1, shout: Bool = false) {
    let msg = shout ? "HELLO, \\(name)!" : "Hello, \\(name)!"
    for _ in 0..<times { print(msg) }
}

greet("Ana")                 // default: once, not shouting
greet("Ben", times: 2)
greet("Cara", shout: true)

Effets et mutabilité

Rendez les effets visibles : utilisez des méthodes mutating pour modifier l’état et exposez des vues en lecture seule avec private(set) lorsque cela est approprié.

// Prefer pure functions when possible; name mutating effects explicitly.
struct Counter {
    private(set) var value = 0
    mutating func increment(by amount: Int = 1) { value += amount }
}

var c = Counter()
c.increment()
c.increment(by: 3)
print("value =", c.value) // 4

Documenter les API

Conseils pour les commentaires de documentation :

  • Commencez par un résumé d’une seule phrase.
  • Indiquez ce qu’elle fait, pas comment.
  • Montrez un petit exemple d’appel.
  • Ne mentionnez les préconditions ou les problèmes de performance que s’ils sont importants.

Justification de l’utilisation des étiquettes

Vérification rapide : quand devez-vous ajouter une étiquette externe ?

Récapitulatif

Récapitulatif : privilégiez des noms clairs, ajoutez des étiquettes qui se lisent bien, proposez des valeurs par défaut pour les appels courants, rendez les effets explicites et gardez une documentation courte accompagnée d’un exemple.

Questions Fréquemment Posées

La leçon « Guide de style et recommandations de conception d’API » est-elle gratuite ?

Oui — le texte complet de « Guide de style et recommandations de conception d’API » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours Swift Academy, passe à CoddyKit PRO. Le cours Swift Academy comprend 3 leçons au total.

Qu'est-ce que j'apprendrai dans « Guide de style et recommandations de conception d’API » ?

Utilisez des noms clairs, des étiquettes d’arguments judicieuses, des valeurs par défaut pertinentes et des commentaires de documentation concis pour concevoir des API Swift agréables à utiliser. Tu pratiques Swift Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer Swift Academy ?

Aucune expérience préalable n'est requise. Swift Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 2 sur 3.

Combien de temps prend la leçon « Guide de style et recommandations de conception d’API » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon Swift Academy ?

Oui. Chaque leçon Swift Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

  1. Bases de SwiftFormat et SwiftLint
  2. Guide de style et recommandations de conception d’API
  3. Documenter le code (introduction à DocC)
← Retour à Swift Academy