Pause café #79. 10 erreurs commises par les développeurs Java qui les empêchent de réussir. Guide du développeur pour rédiger des commentaires de code significatifs

10 erreurs commises par les développeurs Java qui empêchent leur succès

Source : Dev.to Sur la base de mon expérience, j'ai compilé une liste de 10 erreurs commises par les développeurs qui les empêchent de réussir :

1. N'écrivez pas de tests unitaires

Les développeurs qui n'écrivent pas de tests unitaires font plus d'erreurs dans leur code. Cela conduit à une instabilité des produits et à l’insatisfaction des clients.

2. Ils ne vérifient pas le code manuellement

Même si vous couvrez complètement votre code avec des tests unitaires, il est toujours possible que vous ayez manqué quelque chose. Il est toujours recommandé de tester manuellement votre code avant de le soumettre pour révision. De cette façon, vous pouvez détecter les erreurs au stade du développement.

3. Ils pensent : « Cela n’arrivera jamais. »

Les développeurs font souvent des erreurs lorsqu’ils écrivent du nouveau code, pensant que certains scénarios ne se produiront jamais. En fin de compte, il s’avère qu’ils ont tort. Gérez tous les scénarios dans lesquels du code peut être exécuté. Les méthodes de programmation défensives vous y aideront.

4. Ne recevez pas de commentaires

Sollicitez régulièrement les commentaires des autres développeurs et utilisateurs. Partagez votre opinion avec vos collègues.

5. Ils ne vérifient pas la fonctionnalité du code.

Souvent, les développeurs écrivent leur code, mais ne vérifient pas sa fonctionnalité. En conséquence, lorsque le code atteint la production, cela crée divers problèmes.

6. Écrivez un code procédural long

Il est très simple d’écrire de longues méthodes avec beaucoup de logique. En faisant cela, les programmeurs implémentent la même logique à de nombreux endroits. Les projets comportant un nombre important de petites méthodes permettent une bien meilleure réutilisation du code et sont beaucoup plus faciles à maintenir.

7. Ils ne connaissent pas les outils

Les outils sont une extension de vos mains. Mieux vous les connaîtrez, plus vous serez productif. Vous devez être très familier avec l'IDE que vous utilisez. Apprenez des commandes rapides, il y a toujours des commandes qui vous aideront à être encore plus productif. Dans IntelliJ IDEA, il s'agit de Sonar Lint, Spot bugs et Code Metrics.

8. Ignorez les problèmes dans le code

Les développeurs qui travaillent sur les produits les plus performants modifient constamment le code. N'ayez pas peur de refactoriser votre code. Si votre code est testé unitairement, il y a peu de chances de régression. Les développeurs ignorent souvent le code problématique. En tant que développeur, vous êtes responsable du maintien de l’application en bon état. Pour cette raison, résolvez tous les problèmes que vous rencontrez.

9. Ils codent sans se rendre compte des conséquences.

Les développeurs ne doivent JAMAIS apporter de modifications au code et le publier en production sans en comprendre les conséquences. Le code peut produire des résultats corrects pour les valeurs de test données. Cependant, il peut exister des scénarios dans lesquels cela pourrait conduire à des résultats imprévisibles et créer de graves problèmes. Un codage « imprévisible » se produit souvent lorsque les développeurs utilisent des fonctions de bibliothèques qu'ils ne comprennent pas entièrement. Cela peut également se produire lorsqu'un développeur résout un problème sans comprendre la solution.

10. Ne demandez pas d'aide

Les développeurs ne sont pas des gens très sociables. Ils aiment résoudre les problèmes par eux-mêmes. Mais l’époque où un développeur créait lui-même un produit du début à la fin est révolue. Le développement de logiciels est une activité d’équipe. Lorsque vous rencontrez un problème lors de la programmation, essayez de le résoudre vous-même. Mais ne perdez pas trop de temps si vous ne trouvez pas de solution. Il y a de fortes chances que certains de vos collègues aient déjà rencontré le même problème et connaissent la solution. Cela permettra de gagner du temps et d’augmenter la productivité.

Guide du développeur pour rédiger des commentaires de code significatifs

Source : Stepsize Dans la plupart des cas, vous n'êtes pas le seul à travailler sur le même projet ou la même base de code. Cela signifie que d'autres personnes doivent comprendre votre code. Cela est également vrai pour les commentaires de code. Les développeurs écrivent souvent des commentaires « rapides et grossiers » sans beaucoup de contexte, laissant leurs collègues confus quant à ce que l'auteur essayait de dire. Il s’agit d’une mauvaise pratique qui crée plus de confusion que de clarté. Avoir des commentaires de code clairs aide les autres développeurs. Un commentaire de code qui décrit une fonction, sa justification, ses entrées et ses sorties accélère le processus d'apprentissage pour les autres développeurs. D’un autre côté, les commentaires de code nous amènent à la question : est-ce que cela vaut la peine de les écrire ? Un groupe important de développeurs s'oppose à l'écriture de commentaires sur le code. La raison en est que le code, à leur avis, est explicite. Si un autre développeur ne peut pas comprendre le but de votre code en le regardant, alors c'est un mauvais code. C'est peut-être vrai. Mais pensez au petit effort requis pour commenter le code et aux avantages potentiels qu’il apporte. Les commentaires de code sont importants pour accélérer le processus d'intégration de tout développeur, en particulier des juniors. Examinons les différents types de commentaires de code.

1. Commentaires sur la documentation.

L'objectif principal de ces commentaires est de clarifier rapidement l'objectif d'un fichier ou d'un composant. Au lieu de lire l'intégralité du code d'un composant pour comprendre ce qu'il fait, vous pouvez ajouter un commentaire de code en haut du fichier « index ». Cela aidera à expliquer ce que fait ce composant. Je ne suis pas un grand fan de ce type de commentaire car cela encombre un peu le code. Je pense que ces types de commentaires sur l'architecture devraient figurer dans votre documentation interne où vous pouvez gérer et discuter de manière centralisée l'architecture de votre projet. Cependant, les projets open source en ont vraiment besoin.

2. Commentaires sur les fonctions.

C’est le type de commentaire le plus utile. Ils décrivent l'objectif de la fonction, ses paramètres et sa sortie.

/**
 * @desc Creates a welcome message
 */
function sayHello(name) {
    return `Hello ${name}`;
}

3. Commentaires logiques.

Ce sont des commentaires dans les fonctions pour clarifier les chemins de code complexes. Comme vous l'avez peut-être deviné, la présence de tels commentaires indique que votre code est trop complexe. De plus, les commentaires logiques contiennent souvent trop d’informations détaillées. Le niveau de détail créera plus de chaos et réduira la lisibilité de votre code. Voici un exemple de commentaire de code trop détaillé.

let date = new Date(); // store today's date to calculate the elapsed time

Commentaires sur le code : 4 bonnes pratiques pour commenter

1. Utilisez des annotations de code ou des balises

De nombreux langages de programmation définissent des normes pour commenter le code. Java utilise Javadoc , tandis que JavaScript utilise le système de commentaires de code JSDoc , qui est pris en charge par de nombreux outils de documentation. Pour les fonctions, vous devez inclure les balises de code suivantes :

• @desc - description de votre fonction
• @param - tous les paramètres d'entrée acceptés par la fonction. Assurez-vous de spécifier les types d'entrée.
• @returns - sortie renvoyée. Assurez-vous de spécifier le type de sortie.
• @throws est le type d'erreur que la fonction peut générer.
• @example - un ou plusieurs exemples qui montrent l'entrée et la sortie attendue.

Voici un exemple de code Lodash pour la fonction chunk .

/**
 * Creates an array of elements split into groups the length of `size`.
 * If `array` can't be split evenly, the final chunk will be the remaining
 * elements.
 *
 * @since 3.0.0
 * @category Array
 * @param {Array} array The array to process.
 * @param {number} [size=1] The length of each chunk
 * @returns {Array} Returns the new array of chunks.
 * @example
 *
 * chunk(['a', 'b', 'c', 'd'], 2)
 * // => [['a', 'b'], ['c', 'd']]
 *
 * chunk(['a', 'b', 'c', 'd'], 3)
 * // => [['a', 'b', 'c'], ['d']]
 */
function chunk(array, size = 1) {
  // logic
}

2. Expliquez la raison de vos actions

De nombreux développeurs utilisent des commentaires pour décrire ce que fait leur code. Ce faisant, assurez-vous d'inclure la raison pour laquelle vous avez créé une fonctionnalité ou un composant particulier. Cette information est appelée contexte. Le contexte est important pour donner aux développeurs plus d'informations sur les décisions de conception derrière une fonctionnalité ou un composant. Le contexte est essentiel lorsque d'autres développeurs souhaitent apporter des modifications à votre fonctionnalité ou composant. Ci-dessous, vous pouvez voir un mauvais exemple de commentaire de code sans contexte.

/**
 * Sets the label property of a new form.
 *
 * @param label text for label of form
 */
function setFormLabel(label) {
    // logic
}

3. Ne créez pas de liens vers d'autres documents ou commentaires

Il n'est pas recommandé de créer un lien vers d'autres commentaires de code ou documents internes expliquant une fonctionnalité ou un composant.

/**
 * Sets the label property of a new form.
 *
 * @see {@link https://myinternaldocument.com}
 */
function setFormLabel(label) {
    // logic
}

4. Écrivez des commentaires pendant le codage

Cela peut paraître évident, mais de nombreux développeurs (moi y compris) négligent cette règle. Laisser des commentaires pour plus tard est une mauvaise chose car vous risquez d'oublier une partie de la logique que vous avez écrite, ce qui entraînera des commentaires de code de moindre qualité. Cela est particulièrement vrai si vous travaillez sur la même pull request depuis plusieurs jours. Il est préférable d'écrire des commentaires lorsque vous venez de terminer une fonctionnalité ou un module. N'oubliez pas de garder les commentaires de code aussi brefs que possible. Vous n’avez pas besoin de passer plus de temps à rédiger des commentaires qu’à écrire le code lui-même.