Gestion des erreurs – Coder proprement

Le traitement des erreurs est important, mais s’il masque la logique il est mauvais

Utiliser des exceptions à la place des codes de retours

Le message que l’exception lève doit permettre d’identifier l’opération qui a échoué et son contexte

Les classes d’exception sont utiles si c’est pour intercepter une exception et ignorer les autres

Ne pas retourner null, à la place retourner un objet ou une collection vide par exemple

Ne pas passer null en argument, si c’est le cas cela doit être traité comme une erreur avec exception

Objets et structures de données – Coder proprement

Les objets exposent un comportement et masquent les données. Il est ainsi facile d’ajouter de nouvelles sortes d’objets sans changer les comportements existants. Mais il est également plus difficile d’ajouter de nouveaux comportements à des objets existants.

Les structures de données exposent des données et n’ont pas de comportement significatif. Il est ainsi facile d’ajouter de nouveaux comportements à des structures de données existantes, mais difficile d’ajouter de nouvelles structures de données à des fonctions existantes.

Dans un système, nous avons parfois besoin d’une souplesse d’ajout de nouveaux types de données et choisissons alors une implémentation fondée sur des objets. Si nous voulons disposer d’une souplesse d’ajout de nouveaux comportements, alors, nous optons pour les types de données et les procédures.

Si on a des objets hybrides contenant des accesseurs et mutateurs publics ainsi que des opérations alors c’est que l’on a un problème de conception.

Ne pas utiliser de fonctions chaînées tel que :
final String outputDir = ctxt.getOptions().getScratchDir().getAbsolutePath();

Mise en forme – Coder proprement

Faire des petits fichiers sources si possible

Sauter des lignes entre les concepts (import package, déclaration de classe, attributs, méthodes, etc…)

Les variables dans les fonctions doivent être déclarées au début

Les variables d’instance d’une classe doit être déclarées au début

Une fonction qui en appelle une autre doivent être l’une sous l’autre (l’appelant au dessus de l’appelée) ne marche pas en Pascal, C, C++

Les premières fonctions doivent être les plus importantes pour la compréhension, ainsi les fonctions bas niveau sont reléguées à la fin.

Une limite de 120 caractères par ligne est raisonnable

Ne pas aligner horizontalement les affectations de variables entre elles

Toujours développer et indenter les instructions courtes (2 lignes même juste pour un return)

Les règles mises en forme sont à mettre en place avec l’équipe et il faudra la respecter avec des outils de mise en forme (http://editorconfig.org)

Commentaires – Coder proprement

Le meilleur commentaire est celui que vous pouvez éviter d’écrire.

Les “bons” commentaires

– légaux : déclaration de licence
– informatifs : décrire un cas particulier ou complexe (expressions régulières)
– d’explications de décision
– de clarifications : dans les cas où on utilise une librairie ayant des fonctions mal nommées
– d’avertissements
– TODO
– d’amplifications : quand une instruction paraît anodine mais en fait ne l’est pas
– documentations

Les “mauvais” commentaires

– mystiques : seul l’auteur comprend ce qu’il a écrit ou nous fait poser des questions
– redondants/inutiles : le code est plus clair que le commentaire
– trompeurs : une erreur d’explication par rapport au code
– obligatoires : mettre la description des paramètres alors que l’argument parle de lui même
– journalisations : liste des modifications en début de fichier, inutile depuis l’arrivée des systèmes de gestion de versions
– marqueurs de position : ceux qui visuellement délimite le code entre groupes/type de fonctions
– d’accolade fermante : } //end main
– de signature : quand on dit que ce code a été écrit par quelqu’un
– code en commentaire : le code soit il est présent soit on le supprime, mais on le met pas en commentaire
– information non local : explication du port par défaut dans une méthode setPort
– trop d’informations : un extrait d’une RFC
– en entête de fonction : pas besoin si on nomme correctement la fonction

Fonctions – Coder proprement

Corps de la fonction

Ne pas se répéter

Faire court (max 20 lignes)

Faire une seule chose

Ne pas mélanger les niveaux abstractions

Utiliser la règle décroissante : chaque fonction se décrit par un paragraphe décrivant le niveau d’abstraction (en lisant de haut en bas)

Pour inclure les pages de montage et de démontage, nous incluons le montage, puis le contenu de la page de test et enfin le démontage.
Pour inclure le montage, nous incluons le montage d’une suite s’il s’agit d’une suite, puis nous incluons le montage normal.
Pour inclure le montage d’une suite, nous recherchons la page “SuiteSetUp” dans la hiérarchie parente et nous incluons une instruction avec le chemin de cette page.
Pour rechercher le parent…

L’instruction switch ne doit apparaître qu’une seule fois dans la classe la plus haute

Respecter le principe ouvert/fermé : ouvert à l’extension mais fermé à la modification (https://fr.wikipedia.org/wiki/Principe_ouvert/ferm%C3%A9)

Respecter le principe de responsabilité unique : une fonction ne doit être modifié que pour une seule raison pas plus. (https://en.wikipedia.org/wiki/Single_responsibility_principle)

Séparer commandes (faire quelque chose) et demandes (répondre quelque chose)

Nom de la fonction

Utiliser la forme verbe + nom

Il est possible de mettre l’ordre des arguments dans le nom de la fonction

Noms descriptifs et si besoin long : includeSetupAndTeardownPages, includeSetupPages, includeSuiteSetupPage
et includeSetupPage
C’est le principe de Ward : “Vous savez que vous travaillez avec du code propre lorsque chaque fonction que vous lisez correspond presque parfaitement à ce que vous attendiez.”

Arguments de la fonction

Le mieux c’est de ne pas en avoir, le pire est d’en avoir plus de trois (à proscire)

Eviter les arguments indicateurs (bool), pour cela décomposer en 2-n fonctions

Utiliser des objets pour grouper des arguments en un seul

Le nombre variables d’arguments est toujours possible mais pas plus de trois dans la signature de la fonction

Retour de la fonction

Les arguments de sortie sont à proscrire

Utiliser les exceptions

Mettre les bloc try/catch dans leurs propres fonctions (try premier mot et catch/finally dernier mot)

Noms – Coder proprement

Choisir des noms:
– prononçables
– décrivant ce qu’ils fonts sans besoin d’ajouter un commentaire
– pas de jeux de mots
– pas de blague
– pas de préfixe pour le type de variable
– propice à une recherche
– distinction significative
– un mot par concept (add, insert, append)

Si vous avez des chiffres, les assigner à des variables avant le bloc de code

Un nom de classe doit être un nom ou des groupes nominaux (WikiPage)

Un nom de classe ne doit pas être un verbe

Un nom de méthode doit être un verbe ou des groupes verbaux (deletePage)

Les accesseurs, les mutateurs et les prédicats doivent être préfixés par get, set ou is

Quand les constructeurs sont surchargés, vous devez utiliser des méthodes de fabrique statiques avec des noms qui décrivent les arguments
Complex fulcrumPoint = Complex.FromRealNumber(23.0);
Les constructeurs doivent être rendus privés dans la classe qui surcharge.

Avoir un lexique cohérent

Choisir un nom dans le domaine de la solution (JobQueue) ou dans le domaine du problème

Ajouter un contexte aux variables addrState addrCountry mais ne pas faire GSDAccount GSDAccountAddress -> préférer Address PostalAddress MACAddress URIAddress

SEO Summary Techniques

Summary

Search engine optimization (SEO) is the process of affecting the visibility of a website or a web page in a search engine’s unpaid results.

I don’t will explain why I recommand these techniques, there are a lot of websites for that.

So this is my SEO recommandations

Continue reading