09 Productivité développeur

Refactorer et documenter avec Copilot

9.3 Refactoring assisté 🛠️

Définition

Le refactoring consiste à améliorer la structure du code sans changer son comportement externe.

Copilot peut aider à :

  • réduire la duplication ;
  • améliorer la lisibilité ;
  • extraire des fonctions ;
  • simplifier des conditions ;
  • améliorer le typage ;
  • isoler des responsabilités ;
  • rendre le code plus testable ;
  • moderniser une syntaxe.

Exemple simple

Code initial :

js
function getActiveUsers(users) {
  let result = [];
  for (let i = 0; i < users.length; i++) {
    if (users[i].active === true) {
      result.push(users[i]);
    }
  }
  return result;
}

Prompt :

Texte
Refactor this function to make it more idiomatic JavaScript.
Preserve behavior.

Suggestion :

js
function getActiveUsers(users) {
  return users.filter(user => user.active === true);
}

Exemple avec contraintes

Prompt :

Texte
Refactor the selected function.

Goals:
- improve readability
- reduce duplication
- keep behavior unchanged

Constraints:
- do not change the public function signature
- do not introduce new dependencies
- preserve existing error messages
- suggest tests that verify behavior did not change

Ce prompt est très bon pour l’examen.

Refactoring risqué

Mauvais prompt :

Texte
Rewrite this module.

Pourquoi c’est risqué ?

  • scope trop large ;
  • comportement peut changer ;
  • tests oubliés ;
  • dette technique déplacée ;
  • logique métier cassée.

Meilleur prompt :

Texte
Analyze this module and propose a safe refactoring plan.
Do not modify code yet.
Identify tests to add before refactoring.

Exemple legacy

Prompt étape 1 :

Texte
Explain this legacy function and identify behavior that must be preserved.
Do not modify code.

Prompt étape 2 :

Texte
Suggest a refactoring plan that preserves behavior.
Add tests before changing implementation.

Prompt étape 3 :

Texte
Refactor only the selected function.
Keep the public API unchanged.

À retenir

Refactorer avec Copilot = améliorer sans casser.

Toujours demander :

Texte
Preserve behavior.
Do not change public API.
Add or suggest tests.

9.4 Documentation technique 📚

Définition

Copilot peut aider à produire ou améliorer de la documentation technique.

Il peut générer :

  • docstrings ;
  • commentaires utiles ;
  • README ;
  • documentation API ;
  • guides d’installation ;
  • exemples d’usage ;
  • changelog ;
  • résumé de module ;
  • documentation de configuration ;
  • explication d’architecture.

Exemple docstring

Code :

py
def normalize_email(email: str) -> str:
    return email.strip().lower()

Prompt :

Texte
Add a concise docstring explaining purpose, input, output, and edge cases.

Suggestion :

py
def normalize_email(email: str) -> str:
    """
    Normalize an email address by trimming surrounding whitespace and converting it to lowercase.

    Args:
        email: The email address to normalize.

    Returns:
        The normalized email address.
    """
    return email.strip().lower()

Exemple README

Prompt :

Texte
Generate a README section explaining how to run this project locally.

Use:
- package.json scripts
- Dockerfile
- .env.example

Include:
- prerequisites
- installation
- environment variables
- run command
- test command

Copilot peut produire une section claire.

Exemple documentation API

Prompt :

Texte
Generate API documentation for this endpoint.

Include:
- method and path
- required headers
- request body
- response body
- status codes
- error cases
- example request
- example response

Attention aux commentaires inutiles

Copilot peut parfois générer des commentaires évidents.

Mauvais commentaire :

js
// Increment i by 1
i++;

Inutile.

Bon commentaire :

js
// Retry only transient failures. 4xx responses are treated as permanent client errors.

Utile, car il explique une décision métier ou technique.

À retenir

Bonne documentation = explique le pourquoi, les contraintes et l’usage.
Mauvaise documentation = répète ce que le code dit déjà.

À retenir pour le GH-300

  • Un refactoring préserve le comportement et l’API publique sauf changement explicitement demandé.
  • Un bon prompt de documentation demande le but, le contrat, les erreurs, les effets de bord et des exemples vérifiables.
  • Une review Copilot aide à trouver des pistes ; elle ne remplace ni les tests ni la review humaine.

D5 · Productivité développeur · 10–15 %