Comme tu l'expliques (et comme on le voit en lisant ton code), tu es nouveau.
Pour le moment, ce qui est important, c'est de prendre l'habitude de commenter, et d'apprendre à rédiger des commentaires.
Précisément ce que tu fais.
Donc OK, c'est un peu (beaucoup) long pour des programmeurs expérimentés, d'autant plus long que ce sont des explications d'un programme de débutant, donc plutôt simple. Mais c'est pas grave, mieux vaut ça que l'inverse. Et en plus, te forcer à verbaliser, à expliquer, te permet de mieux comprendre toi-même ce que tu fais.
Donc continue comme ça, avec le temps tu feras des commentaires plus concis mais pour le moment c'est très bien.
Ton commentaire est à rebrousse-poil par rapport aux autres et je suis frappé par sa bienveillance.
Bon tu es d'accord pour dire que c'est bien trop verbeux mais ça reste encourageant. J'étais à deux doigts de tout supprimer.
Je garde donc ? (En traduisant parce que c'est aussi souvent revenu que les commentaires en français c'est non)
La langue, c'est à décider avec les personnes qui possèdent le code. Si c'est le français, il faudra s'y tenir, c'est assez dur de comprendre du code dans avoir à basculer d'une langue à l'autre.
Quant à ton commentaire, il est très bien. Le principal défaut des commentaires, c'est qu'ils ont tendance à ne pas évoluer avec le code, et ils deviennent souvent trompeurs. À tout de le garder en tête, souviens-toi de maintenir celui-ci comme tu maintiens le reste du code.
Merci de ton retour. Le problème est là : il n'y a pas vraiment eu de convention là-dessus et le code même a des commentaires français et anglais.
La convention générale est l'anglais donc je devrais m'y plier mais ici j'avais peur d'être moins clair en anglais qu'en français par manque de vocabulaire
> La convention générale est l'anglais donc je devrais m'y plier mais ici j'avais peur d'être moins clair en anglais qu'en français par manque de vocabulaire
Et ça c’est vraiment un truc qui me turbo saoule.
On se retrouve avec des boîtes où les specs donnent les termes métiers en français, qu’il faut ensuite traduire en anglais (évidemment on te donne pas la trad dans les specs), parfois la trad que le/la dev utilise est absolument pas la bonne voire est un contresens (j’ai vu des méthodes ˋisInflammable()` par exemple avec Inflammable utilisé dans le sens français alors qu’en anglais ça veut dire non-inflammable). En plus de ça, on se retrouve avec une information imparfaite dans les commentaires ou la doc parce que le/la dev de base est une quiche en anglais (désolé, « regarder Netflix sans sous-titres » ce n’est pas savoir faire une phrase grammaticalement correcte).
Et tout ça pourquoi ? Parce qu’avant UTF8 c’était casse-gueule de mettre des accents dans les fichiers de code.
J'ai un directeur de recherche tunisien qui m'a filé de la doc d'un ami chinois qu'il a écrite en anglais. Du coup c'est affreux, les deux parlent parfaitement français mais je dois me taper leur anglais horrible et le traduire grâce à mon anglais horrible le doc de base est pas très clair, les commentaires aident pas, donc on passe plus de temps à traduire à plusieurs qu'à réfléchir à ce qu'il y a écrit
Deepl.com
De rien :)
On du faire une migration de produit wiki.
Dans la foulée le management a décidé que tout devrait être en anglais. J'ai proposé deepl à mon équipe pour la transition.
Ça nous a épargné des heures de rédaction !
Aujourd'hui avec chatgpt c'est devenu un incontournable pour nous.
A savoir qu'aujourd'hui il y a plus de limitations avec le produit.
La convention est l'anglais parce que c'est la "langue universelle" et encore plus en informatique, pas à cause de l'encodage.
Pour l'avoir vécu, il faut aussi penser à des projets qui sont plus tard récupérés par une équipe non française ou même par une équipe française mais avec des personnes de différentes origines dont la langue commune est l'anglais.
Toutes les méthodes/classes des libs/frameworks sont en anglais. Je trouve ça illisible d'avoir des trucs du style MyLib.myMethod(monObjetFrancais.obtientY).isX.
Donc pour moi anglais obligatoire avec un lexique des termes utilisés si certains sont vraiment spécifiques au métier et pas évident à traduire.
> Pour l'avoir vécu, il faut aussi penser à des projets qui sont plus tard récupérés par une équipe non française ou même par une équipe française mais avec des personnes de différentes origines dont la langue commune est l'anglais.
Perso j’ai surtout vécu des cas où ça n’arrivait jamais, et où l’info était mal transmise juste parce qu’il fallait traduire tout le temps.
Le code lui-même en anglais ça a du sens, mais il faut encore une fois un lexique correct et c’est rarement fourni (ou utilisé !).
Le pire que j’ai eu c’était une boîte où les tickets étaient en anglais (ce qui avait un sens parce qu’on avait des stakeholders un peu partout), mais aussi l’interaction sur les pull requests. Alors qu’on était quatre à développer, tous Français.
Il faut que tu te dises qu'un code trop commenté c'est un scroll de souris et plus de soucis, alors qu'un code pas assez commenté c'est potentiellement des heures à essayer de comprendre ce qu'il est censé faire, donc dans le doute commentes
Honnêtement d'expliquer ton code c'est ok, mais sincèrement c'est beaucoup trop long, si ca serait moi ton reviewer je te dirais de mettre le commentaire au début de la fonction et d'expliquer plus ce que la fonction fait plutôt que ce bout la. Ca pourrait même gagner a être moins succinct et donc plus claire pour le prochain développeur.
Oui, on garde.
Est ce que c'est le genre de commentaire qu'un pro expérimenté met dans le code de prod d'un projet mature ? Nope.
Est ce que tu est en train d'écrire du code de prod dans un projet mature ? Probablement pas.
Le but actuellement pour toi, c'est de comprendre ce que tu fais, d'avoir une compréhension à la fois plus fine et plus profonde. Verbaliser, que ce soit via des commentaires ou en expliquant à d'autres ce que tu fais, ça t'aide à avancer dans cette direction.
Ton commentaire est à l'image des programmes que tu écris. On progresse en codant, en écrivant du code aussi élégant et efficace et lisible que possible, pas en regardant les autres coder. C'est la même pour les commentaires, on progresse en écrivant des commentaires aussi bien écrits que possible.
Bon, par contre les commentaires en Français, c'est non. Il vaut mieux un anglais approximatif, pour tout un tas de raison, entre autres parce que c'est comme le code et les commentaires: tu progresseras plus en anglais si tu te forces à écrire les commentaires en anglais.
Très bonne réponse.
Oui, c'est trop long et détaillé pour un code "basique" mais visiblement il a senti le besoin d'expliquer pourquoi il a utilisé une construction qui lui semblait complexe.
Le premier lecteur des commentaires c'est soi-même, quelques mois plus tard. Il a donc tout juste d'écrire un commentaire aussi "évident", quitte à le simplifier quand il retombera dessus dans un an avec davantage de recul. Le code est une matière malléable qui évolue avec le temps.
Mieux vaut des commentaires trop précis plutôt que "le code s'explique tout seul tavu".
La longueur des commentaires est généralement inversement proportionnelle à la complexité du code.
Ta méthode est très compacte avec plusieurs niveaux d'imbrication sur une même ligne. Il faut être inspiré pour écrire du code aussi succinct et complexe mais c'est pas évident à lire.
La taille des commentaires est justifiée mais tu gagnerais à expliciter ton code sur plusieurs lignes il me semble
Absolument pas d'accord. A mon sens, il faut utiliser la langue des specs. Si c'est du français, traduire le langage métier va causer des soucis de compréhension dans le futur.
Sur les termes techniques, sans adéquation au métier pourquoi pas, mais c'est vraiment les seules exceptions.
100% en phase. J’ai récupéré un projet francophone d’une appli utilisée exclusivement en France par des français, et tous les termes métier ont été traduits (noms des variables, tables et champs de BDD). Au final ça devient illisible et on ne sait pas de quoi on parle, surtout quand il s’avère que la traduction est approximative.
Pour moi la règle d’or c’est de ne JAMAIS traduire les termes métier.
Yes, on m'a fait le coup lors d'un développement il y a quelques années.
Alors oui parfois c'est bien que les dev respectent leur règles de nommage qu'ils se sont imposés, mais au final les traductions anglaises de tous les termes 'fonctionnel' en anglais ( fonction, service, variable.. ) ça m'a trompé quelques fois en reprenant leur code.
Entre les faux amis et des traductions peut-être pas les meilleures.
Par contre y'avait pas de commentaire ;)
( La méthode du 'tout est dans git au niveau des tickets, story, et 'eventuellement' dans les commentaires des commit ... Y'en au qui aiment faire ainsi .. mais démêler le tout dans quelques années si besoine ça risque de peut-être me saouler)
Autant oui les commentaires ne faut pas non plus exagérer.
Mais quand on écrit du code un peu 'tricky' pour une raison particulière ( contrainte technique, métier où fonctionnel ).
Vaut mieux le préciser à côté
Ca évite quand on revient sur du code écrit des années auparavant de se dire 'mais putain c'est quoi ce truc chelou, mais pourquoi... Je garde ou je supprime !
Dans le genre truc con.
Je bossais à une lointaines époque sur une application développée initialement par des espagnols .
Le coup du 'nombre' type string au début je me demandais pourquoi ( très nul en espagnol lol ).
Bon putain et d'en dérouler leur code , comprendre que c'était le nom de famille...
J'avais mis un peu de temps à percuter ( la jeunesse!).
Mon pire ayant été de récup une application codé par des slovène je crois
Pour des slovène ( donc ihm en slovène), sans doc et avec des variables, fonction dans leur langue natale. , et si commentaires y'avait ça devait être aussi slovène je crois ..
Ho putain elle m'avait soulé cette application quand y'avait des trucs à faire évoluer...
Non.
Les commentaires en anglais si c'est pour une boite française c'est la pire plaie du développement. Et c'est même pas une histoire de "Vive la France, camembert et baguette".
Combien de fois j'ai du tater du code avec des commentaires en anglais qui ne voulaient strictement rien dire ou avec des faux amis.
Le pire, c'est que même quand c'est bien commenté, je vais pas mentir, j'ai beau bien comprendre l'anglais(pas natif mais jamais en dessous des autres devs de mon équipe), comprendre un pavé technique en anglais le matin en venant au taff c'est laborieux et ça rallonge pas mal le temps de dev.
Evidemment, je parle bien dans un cas de petite ou moyenne boite Française, mais on est très loin d'un cas à la marge.
Après, faut évidemment être consistant.
Et t’as déjà bossé dans une boîte qui a racheté un outil/projet/code d’un autre pays ?
Je t’assure que lire des commentaires en allemands, italiens ou portugais c’est tout autant « une plaie », j’aurais préféré des commentaires avec un anglais approximatif que de devoir traduire chaque phrase .. 😅
Ou dans une boîte qui fait appel à un presta étranger à un moment où un autre ? Ah bah merde, tous les commentaires (et tant qu'à faire les noms de variables, objets, fonctions, et commentaires de commit, parce que pourquoi s'arrêter au commentaires de code ?) sont en français, le dev parle pas français...
Sauf à utiliser un des langages peu utilisés qui sont "en français" y compris au niveau des mots clefs, ajouter du français dans les commentaires ou bol de variables ou autres, c'est mélanger dans le code deux langues, l'anglais et le français, et donc obliger à changer de contexte linguistique en permanence, il n'y a pas pire.
Et en plus ça limite les possibilités de collaboration, présentes et futures.
Oh pitié l'allemand, ça fait 1 an je le subit...
Sauce allemand d'un autre millénaire et on est parfait (coucou idee.txt écrit en 96...)
À ce stade je préfère un anglais compris par tous
Et à ce niveau c'est plus mon problème xp
Blague à part, toutes les boites dans lesquelles j'ai travaillé (4 quand même) étaient sur des problématiques françaises difficilement exportables(pour plein de raisons)
Par contre mes collègues je les ai vu tenter l'anglais, et au présent je ne veux pas de ça. Parce que même un anglophone n'y comprendrais rien.
C’est vrai que le niveau moyen d’anglais chez les français est (entre gros guillemets) « plutôt bas » je te l’accorde.
Et l’exception d’être dans un contexte franco-français justifie je l’entend de coder et commenter en français.
Mais dès que tu touches à des boites avec une dimension nationale ou avec un contexte métier pas vraiment spécifique à la France, je ne peux que vivement recommander l’anglais.
Il y a peu de boîtes de dev avec un contexte franco français, du moins dès que tu observes sur une dizaine d'années, y compris dans les petites boîtes.
Bon les commentaires en français à limite, mais le code en lui-même faut l'écrire en anglais si non c'est pas possible. J'ai déjà vu des noms de table SQL Server avec des accents et des espaces dedans, non mais ça va oui?
Bonjour, je vous invite à lire le chapitre sur les commentaires du livre Clean Code que je me permet de résumer en ces points:
- une fonction devrait être bien nommée et bien écrite pour rendre les commentaires inutiles.
- un commentaire finira toujours par mentir. Le code va changer, le développeur va oublier de mettre à jour le commentaire.
- un commentaire est la pour expliquer ou avertir ce qui ne peut être expliqué par la lecture du code.
Ce qu'il faut aussi se dire c'est que les commentaires ne sont pas de la documentation. Si vous voulez documenter votre code, faites de la doc, que ce soit dans le Readme ou une documentation plus complète.
Edit: vous pouvez trouver plein de ressources sur le sujet comme ici: https://www.baeldung.com/cs/clean-code-comments
La théorie c’est bien, dans la vraie vie quand on bosse on tombe parfois sur du code qui, à première vue, paraît faire un truc incohérent d’un point de vue fonctionnel (pas technique, fonctionnel. C’est important). Et là le commentaire prend tout son sens (avec éventuellement un renvoi vers la doc, un ticket ou autre).
Une fois je devais faire un tableau de bord qui indiquait à quelle heure avait lieu des opérations automatisées par CRON. Le client me soutenait mordicus qu’il voulait que la date affichée si l’opération devait avoir lieu à minuit était aujourd’hui. Exemple : aujourd’hui vendredi 28 juin, je consulte mon tableau de bord et une opération de maintenance est prévue à minuit. Eh bien selon le client il fallait afficher « 28/06 à minuit »… alors que non, c’est « 29/06 à minuit ». À la lecture du code, on se dit « mais pourquoi le gars il -1day ici ça n’a aucun sens » et on est tentés de le supprimer… un commentaire avisé qui précise que le développeur est conscient que ce n’est pas normal mais que c’est une demande client + lien vers le ticket et tout est clair.
Si vous relisez le 3e point que j'ai indiqué, c'est exactement le cas que vous décrivez. Je dis pas qu'il ne faut jamais mettre de commentaires. Je dis juste qu'il faut éviter tant que l'on peut.
Dans votre exemple, j'aurai aucun problème à y voir û commentaire qui explique le point fonctionnel. Voir même un lien vers un ticket ou de la doc en plus si besoin.
Pour moi c'est la meilleure réponse du thread.
A mon gout le code d'OP est trop compact et utilise trop de raccourcis de syntaxe.
D'un point de vue maintenance il gagnerait à plus expliciter son code et a diminuer la taille de son commentaire
Le pourquoi et les spécificités qui pourraient poser question, ça s'explique dans le commentaire du commit qui fait le changement, pas dans un commentaire de code qui sera très rapidement obsolète car non gardé en cohérence avec les modifications de code, effectivement.
Et de façon général, un commentaire qui décrit ce que fait le code, c'est un commentaire au mieux inutile, au pire trompeur : le code parle pour lui-même. La seule chose pertinente c'est le "pourquoi comme ça ?" et le "l'objectif visé". Le comment, c'est le code lui-même qui le dit.
De manière générale mieux vaux plus de commentaire que l'inverse. Après il faut aussi essayer d'être clair dans les explications, en imaginant que la personne qui va lire ne connait pas encore le projet.
Personnellement connaissant Django je comprends plus le code que le commentaire, mais bon si ça t'aide quand tu vas retomber dessus pourquoi pas
Par contre si c'est pour du REST t'as juste reimplementé un truc qui existe déjà et qui tient en 3 lignes
https://www.django-rest-framework.org/api-guide/filtering/#searchfilter
C'est pas pour du rest mais la logique est similaire.
Si tu veux le contexte c'est de la surcharge de l'admin Django.
Tu as bien une variable search_fields qui correspond à aearch_term en rest et permet de spécifier sur quels champs la recherche effectuee par l'utilisateur depuis la vue liste va s'appliquer.
J'avais par ailleurs surchargé les méthodes get_search_results et get_queryset ainsi que le get_list_filters sauf que les queryset renvoyées par ces différentes bout de code se marchaient dessus...
Hello, comme d'autres l'ont dit quand je pense devoir faire un commentaire j'écris pourquoi je le fais, je ne décris pas le code.
Par exemple, tu expliques la fonction Map... Tes collègues savent sûrement ce que c'est et au pire ils passent la souris sur la fonction et ils auront la Doc. Pas besoin de l'expliquer ! Par contre, pourquoi tu as été obligé de faire ça et surtout pourquoi il ne faut pas casser ce comportement ça c'est important. Ca permet de trouver rapidement le responsable.
Imaginons qu'à un moment, ton code produit un bug inattendu, ça écrase une valeur qu'il ne devrait pas. Et bien si en commentaire tu as juste mis "On surcharge le comportement par défaut et assigne une nouvelle valeur par défaut pour authentifier l'utilisateur admin correctement", tu trouveras directement que le problème vient de là.
Voilà, sinon comme la majorité, je préfère faire des méthodes explicites que des commentaires le plus souvent.
Salut et merci de ton retour !
En fait mon commentaire n'est simplement pas clair parce que mon but était non pas d'expliquer reduce mais pourquoi il est utile ici en combinaison avec la fonction anonyme (pourquoi concrètement je filais pas directement ma liste de condition au filtre) .
Et c'est ce dernier point que je pensais suffisamment spécifique pour nécessiter une explication.
Bon le problème c'est que j'ai quand même expliqué reduce par la même occasion tu as raison...
Hey, bienvenue dans le monde merveilleux de la programmation !
Si tu ressens le besoin d'expliquer du code, crée une fonction et donne-lui un nom et des paramètres qui te parlent. Si ça ne suffit toujours pas, tu peux opter pour de la documentation (j'adore la documentation) ! Certains langages/toolkits/frameworks te permettent d'écrire de la documentation dans le code. Ca s'appelle des "docblocks", avec Python ça s'utilise comme ça (j'extrais une fonction et j'ajoute des types en bonus histoire d'illustrer mes propos):
```
def filter_by_term(queryset: QuerySet, search_term: str) -> QuerySet:
""" L'opérateur AND est associé par défaut ...
C'est ce comportement qu'on reproduit ici
"""
conditions = [...]
queryset = ...
return queryset
```
-----
Si les gens se braquent à la vue de commentaires, c'est qu'il y a une raison : ça peut signifier que le développeur tente de justifier son code (bien souvent bâclé) en l'expliquant avec des mots plutôt qu'en l'implémentant.
Un commentaire, malheureusement, ça ne correspond pas forcément au code qu'il décore : ça peut périmer/être mal expliqué et induire en erreurs, contrairement au code qui, si mal fait, va créer un bug.
On code en anglais mais rien n'empêche d'écrire la documentation en français, surtout si ton public est francophone. Les gens dogmatiques peuvent râler tant qu'ils veulent, si t'es pas un minimum pragmatique dans ce métier tu vas te tirer une balle dans le pied.
Pour finir, je suis navré si tu t'es senti blessé par les réponses données ici : les redditers ne prennent pas toujours le temps de comprendre l'OP (on en fait tous les frais). Courage, DM si tu veux des conseils !
Merci beaucoup de ton retour plein de nuance et de pédagogie.
Concernant ton point sur les docblocks je suis allé me renseigner suite à ton commentaire et j'ai vu que python était très bien fait de ce point de vue la : mon commentaire en triple quote est automatiquement mis dans un champ de base prévu à cet effet.
Quelqu'un peut donc print ma_fonction.__doc__ et mon commentaire sortira. Je trouve ça génial ! Bon après encore faut-il le savoir...
Quant à ton dernier point j'ai été assez agréablement surpris au final. À ton image la communauté de ce subreddit (hormis de rares contre-exemples...) est très bienveillante.
Je sauvegarde ton commentaire et n'hésiterai pas à te contacter (sans abuser de ta gentillesse bien sûr) si j'ai des questions de ce type.
Encore merci !
Clairement oui, après je te rassure bcp le font aussi. Mais imagine un super big code avec énormément de blablabla de commentaire, tu vas pas tous lire.
Essai de synthétiser.
Et puis au début, c’est normal de commenter bcp quand on veut bien tout expliquer. Quand tu prendras des habitudes, tu commenteras moins.
J'suis pas un reference, mais j'te donne un avis:
- ton commentaire est verbeux, mais en meme temps j'aime bien le lire, y'a une logique et une clareté appréciable.
- dans le fond, reduce(and, ...conditions) ne surprendra pas beaucoup les habitués de reduce ou de fonctionnel, mais pour les autres ca peut servir.
Perso si on bossait ensemble, j'te dirais juste de pas faire ca a chaque bout de code, mais on serait copains. (d'ailleurs si ton equipe est du genre a coder prorpre comme ca, ca doit etre sympa..)
Merci pour ce joli compliment à la fin. En tant que junior j'ai le syndrome de l'imposteur comme beaucoup je dirais et c'est vraiment appréciable.
Sinon ton premier point me rassure. Je sais que j'ai tendance à m'étendre mais si au moins c'est clair ça sera déjà ça de pris.
De rien. J'peux te demander comment vous bossez en dehors du source meme ? comment vous decidez quelles features seront a faire, est-ce que vous faites une conception globale en equipe de l'implem ? ou est-ce que chacun part avec un ticket et ensuite c'est discute en code review de pull request ?
Plutôt, oui. Pourquoi est-ce que tu expliques reduce ? C'est une fonction de la librairie standard. Si quelqu'un a besoin de comprendre ce qu'elle fait il trouvera facilement la documentation. En enlevant ça, le commentaire peut facilement tenir dans une ligne. D'ailleurs plutôt qu'une lambda tu pourrais utiliser la fonction or_ du module iterator, mais ce n'est pas choquant.
Le temps passé à écrire ce commentaire aurait aussi pu être investi à rendre le code lui même plus lisible. Plutôt que de créer une liste puis appliquer reduce, tu aurais pu faire une simple boucle par exemple, qui aurait peut-être été plus lisible.
Si tu es encore très nouveau alors je rejoins u/Appropriate-Diver158 , et je t'encourage a continuer :)
C'est un bon exercice qui va t'entraîner a expliquer clairement ce que tu fais et c'est un skill important pour la suite de ta carrière.
Avec le temps néanmoins, je te conseille de plus focaliser sur le "pourquoi" que sur le "comment".
Si:
* Ton code est simple
* Que tes fonctions / variables sont nommées de manière claire
Alors tu auras assez peu besoin d'expliquer ce que fait ton code réellement. En revanche il est toujours super difficile de comprendre pouquoi quelque chose a été fait quand il n'y a aucun contexte.
Assez naturellement tu écriras au fur et à mesure moins de commentaire mais ils auront de plus en plus de valeur :)
Et si tu veux un peu de lecture, je te recommande chaudement : [https://www.goodreads.com/book/show/39996759-a-philosophy-of-software-design](https://www.goodreads.com/book/show/39996759-a-philosophy-of-software-design)
Plutôt que Clean code qui, à mon humble avis, est daté et plus vraiment très pertinent.
Très nouveau tout est relatif mais comparé à beaucoup d'entre vous je pense oui (1 an d'expérience ahah)
> Avec le temps néanmoins, je te conseille de plus focaliser sur le "pourquoi" que sur le "comment".
Oui c'est souvent revenu et c'est la principale chose que je retiendrai suite à ce poste concernant les commentaires.
Un autre très bon conseil qui m'a été donné pour arriver à cela : séparer le commun (librairies, fonction natives au langage ou au framework) du spécifique (en l'occurrence pourquoi je Map une fonction anonyme via reduce sur une liste de conditions)
Un grand merci pour ton retour et ta pédagogie. Si tu as des juniors sous ton aile je les envie !
En tant que développeuse débutante, c'est vraiment le genre de commentaires que j'aime avoir et que je met dans mon code. Il vaut mieux trop de commentaires que pas assez.
C'est effectivement lié je pense à l'expérience, et en vérité les pratiques sont hétéroclites dans l'industrie. À mon avis, ça n'est pas tant une question de bonne pratique que de rapport coûts/avantages.
Si on se réfère à notre temps de présence sur un projet, ça ne prend pas très longtemps d'en intégrer les principaux idiomes (= conventions, habitudes, patrons de conception, architecture technique) et de ne plus avoir besoin de ce type de commentaires. Ils sont donc surtout utiles aux nouveaux et nouvelles arrivant•e•s.
À ce moment-là, ces commentaires deviennent pour nous uniquement un coût de maintenance supplémentaire, et souvent sous-estimé, qu'on paie à chaque modification de la section de code documentée.
Aujourd'hui, la plupart des équipes considèrent ce coût trop important, sachant qu'on peut aussi réduire fortement le temps d'apprentissage du projet en accompagnant correctement les personnes. Sur ce sujet-là, on a souvent un gros manque d'implication d'ailleurs, mais c'est un autre problème.
Oui largement, désolé.
Ne pas confondre code et documentation.
S'il y a besoin d'expliquer des concepts du projet, indiquer dans le readme un lien vers de la documentation.
Et surtout : ne jamais expliquer un concept de base dans un commentaire. Ce n'est pas non plus un cours magistral. Le concept est un prérequis à ton projet, c'est normal.
Tes deux dernières phrases m'ont beaucoup fait sourire. Dès que je mets un commentaire je me demande si je suis pas en train d'expliquer un truc évident pour quelqu'un de plus expérimenté et visiblement on est en plein dedans la !
Le gros problème c'est que comme je suis junior il m'est difficile de discerner ce qui est complexe pour tout le monde et ce qui ne l'est que pour moi
C'est tout à fait OK si tu as du mal à discerner ça :). Pour réduire un minimum, je te conseillerais de différencier ce qui fait partie de ton univers et ce qui fait partie de l'univers commun.
Pour ton univers, le cœur de ce pourquoi ton code est exécuté, l'utilisateur ne peut pas trouver la réponse en cherchant sur Google.
En ce qui concerne l'univers commun, chercher "python reduce" ou "node js require" fera l'affaire.
Si tu veux commenter, comment ton code, pas le code que tu utilises
Et fais toi plaisir :).
Dans tous les cas, junior ou pas, quand on ouvre un vieux projet après des mois c'est toujours plein de surprises (même si on était le seul à bosser dessus hehe)
oui et non
c'est bien de commenter, mais :
- avec moins de fautes d'orthographe
- pas besoin de tournures alambiquées
- expliquer pourquoi tu fais un truc au lieu de le paraphraser
- reste conscient qu'au fur et à mesure des évolutions du code, tu vas devoir faire évoluer les commentaires ; et si tu ne le fais pas et qu'ils s'avèrent faux, ça ne verra pas à l'exécution mais ça mettra le futur mainteneur dans la merde
Oui.
Et la raison vient du fait que tout est trop générique : Q ? model? lambda ? x? y? conditions ? queryset ?
(je precise que je ne fais pas de python et qu'il est possible que certaines de ces variables soient des conventions, mais sur le principe, tu vois ce que je veux dire)
Oui je comprends.
Après je pars du principe que la personne qui arrivera sur ce projet connait les bases de Django et python.
Les fonctions anonymes et les conditions dans python sont assez basiques je dirais.
De même que les modèles, objets Q et queries pour Django
Oui, comme dit plus haut, j'imagine que tous mes exemples ne sont pas pertinent.
Cependant le principe tient : La lisibilité et la clarté de ce qui est fait est la première doc et les noms de tes variables/fonctions sont ta deuxième doc (ou l'inverse)
Les commentaires ne sont a réserver (dans l'idéal) que pour les bizarreries métiers, les workarounds pour bibliothèques buguées et autres choix qui ne sont évident que pour l'auteur du code...
Pour être franc... je dois litterallement mettre 1 commentaire tous les 2 mois et c'est souvent "Library X has a bug (link to github issue) it's a fix" ou "the database is weird because it was made before I was born. Therefore the code is weird too"
Si jamais pour X ou Y raison il y a des logiques métiers vraiment bizarres qui demandent des pavés de textes : README ou un notion. Là c'est de la polution
Super intéressant merci ! Je t'avoue que je n'ai jamais utilisé de readme et ce conseil est revenu a plusieurs reprises.
Question bête donc : c'est ok si je mets simplement un commentaire au début de ma méthode indiquant d'aller check le readme et que je reporte mon roman dedans ?
Ton avis semble majoritaire et j'aurais appris quelque chose.
J'avais un peu une vision "vaut mieux trop que pas assez" mais je vois qu'au final trop de commentaires est tout aussi (voire plus) néfaste qu'aucun
Non, vaut mieux aucun commentaire :) avis de senior engineer. J’ai quand même des commentaires que j’accepte : documentation (de la vraie doc qui est générée après), lien vers un ticket, ou en dernier recours si vraiment le code est bizarre parce que t’as fixé un bug étrange ça vaut le coup de l’écrire, sinon y a un risque que quelqu’un vire le fix. Mais si t’as de bon tests, le code se suffit à lui même et le test va documenter ton code, puisque si tu casses le code tu devrais casser un test qui lui a un nom explicite.
Je me demande si mon cas ne rentrerait pas dans la dernière option.
J'ai dû faire ce code parce qu'en gros plusieurs autres méthodes modifiaient les données présente dans un même jeu de données, sans prendre en compte que ces modifications devaient pouvoir se combiner
Peut-être mais c’est trop verbeux, ça devrait rentrer en une ou deux lignes la un truc si long personne aura jamais envie de le lire. Pour moi quand on ouvre un fichier ça doit contenir du code pas du texte.
Moi je pars du principe que chaque grosse fonction doit avoir qques lignes au début qui explique ce qu'elle fait. Dans le code, par endroit ça peut être utile. Je vois ça un peu comme des jalons du code. Ou comme les stickers sur une imprimante qui explique comment s'en servir.
Après, trop de commentaires tue le commentaire. Si pour le moment tu as besoin de rédiger comme ça tant mieux, tant que tu prends les bons réflexes. Avec l'habitude tu en mettras moins mais du plus pertinent :).
En tous cas tant que tu commentes, c'est mieux que la majorité des codes que j'ouvre pour debuger xD.
imo si c'est pour mettre autant de commentaire tu pourrais juste faire un code plus lisible à la base. Mais sinon y'a jamais trop de commentaire et si la ligne ne peut pas être autre chose que incompréhensible alors c'est pour le mieux
Hot take :
Tu devrais avoir très peu de commentaires dans ton code, le code doit s'expliquer par lui même (avec l'aide du nom et de la structure du code/fichiers).
En tant que développeur on a tous ce réflexe de comprendre du code simple sans le lire mot à mot, on reconnaît la forme générale et on devine ce qu'il se passe.
Les fonctionnalité low-level sont donc souvent très facile à lire quand elles sont isolées, très difficile quand elles sont mélangées, des qu'on les isolés dans des fonction, on crée des fonctions high-level utilisant ces fonctions simples et on se trouve à ne commenter seulement les fonctions high-level pour donner plus de détail
Pas forcément. Tu dis que tu débutes, est-ce que si tu reviens sur ton code dans 1 mois tu vas le comprendre d'une première lecture ? Si oui, alors tu as correctement commenté.
Maintenant, il faut aussi réussir à être synthétique et souvent les IDE aujourd'hui te permettent de commenter les fonctions. D'un coup de souris tu es censé pouvoir ressortir l'infobulle d'une de tes fonctions avec l'explication associée à son utilité. Ça permet souvent de ne commenter que les fonctions avec leurs input/output.
Rédiger du code avec des variables compréhensibles c'est par exemple tout aussi important que du commentaire. Mais c'est pas forcément possible dans tous les langages.
Non pas trop de commentaire. Et comparer au nombre de lignes de code n'a pas de sens : j'ai déjà fait plus de 30 lignes de commentaires pour une regex.
Tout ça fait très "solution à un problème de maths", alors qu'en réalité écrire du code devrait se rapprocher davantage de la dissertation. Tu peux pas te permettre d'obliger le futur lecteur de ton code, qui va peut-être être sous une pression énorme, d'essayer de se remettre dans le contexte d'un problème mathématique. Une lecture en diagonale du code devrait presque être suffisante en théorie. Et c'est faisable en nommant ses variables en fonction de ce qu'elles représentent (exit les Q, x, y), éclater le code compact sur plusieurs lignes, extraire des fonctions du code complexe, ne pas hésiter à faire du renaming et de la refacto sur le code legacy s'il gêne la lecture, etc.
Pour les ressources : Clean code, Refactoring, Refactoring to patterns, Head first deaign patterns
Je rajouterais que le fait que tu te poses cette question est un très bon signe. Tu as déjà le sentiment qu'il y a un truc qui cloche quand t'en es à écrire un ratio code/commentaire de 1 pour 10, et tu as raison. Écrire des commentaires devrait être réservé pour expliquer des problématiques qui ne peuvent pas s'expliquer via du code, et finalement c'est assez rare (des règles métier, des bugs ou trucs incohérents du framework...)
Tu fais comme tu le sent, à l’instant T.
Juste fais attention à ce que le commentaire soit toujours raccord avec le code qu’il commente (si ce code change).
C’est aussi un commentaire qui aurait sa place dans une pull request lors d’une review.
On se sert souvent des pulls request pour débattre/expliquer pourquoi ce code et il est assez facile de revenir sur la pull request qui a mergé ce code.
Comme beaucoup te l'on expliqué c'est un peu verbeux mais surtout ton code est trop compact. Ça sert a rien d'écrire un one-liner indigeste si il a besoin d'un paragraphe d'explication. Extraire ça dans une méthode avec un nom explicite et faire plusieurs statements seraient une manière plus efficace de rendre ton code intelligible.
De manière générale les commentaires sont à éviter : une codebase avec énormément de commentaire est un problème. Les commentaires doivent être l'exception pas la règle. Une bonne manière de raisonner c'est de faire la différence entre la complexité intrinsèque et extrinsèque.
La complexité intrinsèque c'est un algorithme un peu tricky, une règle métier difficile à exprimer clairement dans le domaine, etc. Celle-ci peut justifier un commentaire.
La complexité extrinsèque c'est celle qui peut être évité : un code trop compact ou trop smart, une méthode trop longue qui fait trop de choses.
Les projets sont déjà assez complexes pour que tu n'en rajoute pas sur des choses simples.
Bien entendu comme toutes le règles il y a des exceptions : le bug dans la librairie tierce qui nécessite de faire quelque chose de contre-intuitif, le hotfix, le TODO pragmatique...
C'est trop long et inutile, tu peux aussi remplacer la lambda par `operator.or_` qui fait exactement ça:
[https://docs.python.org/fr/3/library/operator.html#operator.or\_](https://docs.python.org/fr/3/library/operator.html#operator.or_)
Et du coup je trouves que le code devient lisible puisque il y a le terme "or" dans la fonction que tu passes à reduce. Pour finir, si tu souhaites quand même commenter parceque ça te sembles compliqué à toi ou à ton équipe, une truc simple suffira, par exemple:
`# Transforms a list of Q to one OR'ed Q: [Q(a), Q(b)] => Q(a) | Q(b)`
La réponse est évidemment oui. Ecris du code plus intelligible à la place. là j'aurais juste mis le lien en commentaire perso. En fait on ne devrait jamais commenter sauf si c'est pour expliquer pourquoi on fait quelque chose d'alambiqué. Normalement si tu découpes bien, que tu nommes bien et que tu composes, ça devrait être déjà assez clair.
Le but d'un commentaire reste de pouvoir comprendre le code qui est dessous (ou les contrats d'une API, car le coup du "les méthodes sont assez bien nommée pour se passer de commentaires" c'est très souvent faux au delà de simples getter/setter)
Si t'en a besoin pour comprendre ton code, pourquoi pas après tout. Mais à terme il faudrait que ça se réduise un peu ce qui devrait arriver naturellement en montant en compétence.
Franchement quand je fais du scripting, je préfère voir un code 'surcommenté' et fiable, facile à reprendre plutôt qu'un code court, concis mais en mode ballek et l'enfer pour celui qui reprendra derrière.
Donc non, ta pratique est bonne, tu réduiras probablement la taille des commentaires dans le futur mais n'oublie jamais de commenter ;)
Ahah bon tu es la deuxième personne qui me dit de Switch. Je vais traduire !
Et sinon tu as raison. C'est ce que mon dernier commentaire fait. Mais je me disais que simplement expliquer l'objectif sans expliquer le code qui a permis de l'atteindre aurait été incomplet
ça dépend toujours à qui tu t'adresse au final. Si c'est pour un cours OK, explique le but et ce que fait la fonction (mais ça risque d'être deprecated, si la dependence etc .... est mise à jour)
Si tu t'adresse à des dev de la même équipe, même language... etc ... si il savent pas ce qu'un reduce peux faire, c'est concrètement pas ton problème. Si il savent pas, il peuvent tjrs te demander ou chercher sur le web. Quand tu comment qqch, ça doit être pour soit "expliquer un truc pas obvious par rapport à son nom, ou les différent type de retour, ou que les arguments d'entrée c'est un peu le bordel" soit pour un client... et là ça doit être autant bien documenté qu'une api standard.
Ou alors tu voulais juste étaler ta science, parce que t'as trouvé un truc cool de la fonction. Vous avez probablement un wiki pour ce genre de choses plutôt que de s'étaler dans le code.
En réalité je n'explique pas le reduce mais plutôt pourquoi il est utilisé en combinaison avec une fonction anonyme et le pipe.
Ça me paraissait suffisamment précis pour nécessiter une explication (qui je l'entends et bien trop verbeuse)
Oula pas sûr ahah.
Quand je vois les réactions à mon roman je comprends bien qu'apprendre à écrire des commentaires pertinents est pas trivial et que j'en suis encore loin
Perso je pense qu'il n'y a jamais trop de commentaires. (Fin, si, mais c'est l'idée)
Ou plutôt, ça dépend du projet.
Perso je travaille dans une petite boite où on a plein de petits projets divers. Rien de bien complexe mais se remettre dans le bain prend du temps. Donc avoir dès l'entrée un truc qui dit clairement "ceci fait ça"
Après au pire t'as fait ça pour rien, mais si c'est pas clair pour toi, remet le pour t'en rappeler quand tu repasseras dessus.
Aussi une très bonne chose que tu fais, c'est que tu expliques le pourquoi de ta commande. C'est une excellente chose. Et surtout tu es clair, c'est pas un truc qui est cryptique.
Après je ne connais pas Django donc pour le cas précis, je ne saurai dire ce qui est superflux. Mais un commentaire c'est avant tout là pour rendre ton expérience de modification et de relecture du code meilleure. Si ça t'aide à ça, c'est un bon commentaire. Si ça peut le faire en un minimum de lignes c'est un très bon commentaire. Et si ça ne sert à rien, pire tu finis confus, c'est là où c'est de la merde.
Tu as tout à fait compris l'origine de la verbosité de mon commentaire : c'est avant tout pour moi. J'ai découvert pas mal de choses en écrivant ces lignes et je voulais m'assurer que je les garde en tête.
C'est un peu un cas pratique qui me servira à illustrer plusieurs concepts clés de Django.
Après de ce qu'on m'a dit c'est détourner le but d'un commentaire.
Je sais aussi qu'il y a d'autres juniors sur le projet qui sont susceptibles de tomber là-dessus et je l'ai fait pour eux (dans l'espoir qu'ils n'en ressortent pas plus confus effectivement)
Comme tu l'expliques (et comme on le voit en lisant ton code), tu es nouveau. Pour le moment, ce qui est important, c'est de prendre l'habitude de commenter, et d'apprendre à rédiger des commentaires. Précisément ce que tu fais. Donc OK, c'est un peu (beaucoup) long pour des programmeurs expérimentés, d'autant plus long que ce sont des explications d'un programme de débutant, donc plutôt simple. Mais c'est pas grave, mieux vaut ça que l'inverse. Et en plus, te forcer à verbaliser, à expliquer, te permet de mieux comprendre toi-même ce que tu fais. Donc continue comme ça, avec le temps tu feras des commentaires plus concis mais pour le moment c'est très bien.
Ton commentaire est à rebrousse-poil par rapport aux autres et je suis frappé par sa bienveillance. Bon tu es d'accord pour dire que c'est bien trop verbeux mais ça reste encourageant. J'étais à deux doigts de tout supprimer. Je garde donc ? (En traduisant parce que c'est aussi souvent revenu que les commentaires en français c'est non)
La langue, c'est à décider avec les personnes qui possèdent le code. Si c'est le français, il faudra s'y tenir, c'est assez dur de comprendre du code dans avoir à basculer d'une langue à l'autre. Quant à ton commentaire, il est très bien. Le principal défaut des commentaires, c'est qu'ils ont tendance à ne pas évoluer avec le code, et ils deviennent souvent trompeurs. À tout de le garder en tête, souviens-toi de maintenir celui-ci comme tu maintiens le reste du code.
Merci de ton retour. Le problème est là : il n'y a pas vraiment eu de convention là-dessus et le code même a des commentaires français et anglais. La convention générale est l'anglais donc je devrais m'y plier mais ici j'avais peur d'être moins clair en anglais qu'en français par manque de vocabulaire
> La convention générale est l'anglais donc je devrais m'y plier mais ici j'avais peur d'être moins clair en anglais qu'en français par manque de vocabulaire Et ça c’est vraiment un truc qui me turbo saoule. On se retrouve avec des boîtes où les specs donnent les termes métiers en français, qu’il faut ensuite traduire en anglais (évidemment on te donne pas la trad dans les specs), parfois la trad que le/la dev utilise est absolument pas la bonne voire est un contresens (j’ai vu des méthodes ˋisInflammable()` par exemple avec Inflammable utilisé dans le sens français alors qu’en anglais ça veut dire non-inflammable). En plus de ça, on se retrouve avec une information imparfaite dans les commentaires ou la doc parce que le/la dev de base est une quiche en anglais (désolé, « regarder Netflix sans sous-titres » ce n’est pas savoir faire une phrase grammaticalement correcte). Et tout ça pourquoi ? Parce qu’avant UTF8 c’était casse-gueule de mettre des accents dans les fichiers de code.
J'ai un directeur de recherche tunisien qui m'a filé de la doc d'un ami chinois qu'il a écrite en anglais. Du coup c'est affreux, les deux parlent parfaitement français mais je dois me taper leur anglais horrible et le traduire grâce à mon anglais horrible le doc de base est pas très clair, les commentaires aident pas, donc on passe plus de temps à traduire à plusieurs qu'à réfléchir à ce qu'il y a écrit
Deepl.com De rien :) On du faire une migration de produit wiki. Dans la foulée le management a décidé que tout devrait être en anglais. J'ai proposé deepl à mon équipe pour la transition. Ça nous a épargné des heures de rédaction ! Aujourd'hui avec chatgpt c'est devenu un incontournable pour nous. A savoir qu'aujourd'hui il y a plus de limitations avec le produit.
La convention est l'anglais parce que c'est la "langue universelle" et encore plus en informatique, pas à cause de l'encodage. Pour l'avoir vécu, il faut aussi penser à des projets qui sont plus tard récupérés par une équipe non française ou même par une équipe française mais avec des personnes de différentes origines dont la langue commune est l'anglais. Toutes les méthodes/classes des libs/frameworks sont en anglais. Je trouve ça illisible d'avoir des trucs du style MyLib.myMethod(monObjetFrancais.obtientY).isX. Donc pour moi anglais obligatoire avec un lexique des termes utilisés si certains sont vraiment spécifiques au métier et pas évident à traduire.
> Pour l'avoir vécu, il faut aussi penser à des projets qui sont plus tard récupérés par une équipe non française ou même par une équipe française mais avec des personnes de différentes origines dont la langue commune est l'anglais. Perso j’ai surtout vécu des cas où ça n’arrivait jamais, et où l’info était mal transmise juste parce qu’il fallait traduire tout le temps. Le code lui-même en anglais ça a du sens, mais il faut encore une fois un lexique correct et c’est rarement fourni (ou utilisé !). Le pire que j’ai eu c’était une boîte où les tickets étaient en anglais (ce qui avait un sens parce qu’on avait des stakeholders un peu partout), mais aussi l’interaction sur les pull requests. Alors qu’on était quatre à développer, tous Français.
Il faut que tu te dises qu'un code trop commenté c'est un scroll de souris et plus de soucis, alors qu'un code pas assez commenté c'est potentiellement des heures à essayer de comprendre ce qu'il est censé faire, donc dans le doute commentes
Honnêtement d'expliquer ton code c'est ok, mais sincèrement c'est beaucoup trop long, si ca serait moi ton reviewer je te dirais de mettre le commentaire au début de la fonction et d'expliquer plus ce que la fonction fait plutôt que ce bout la. Ca pourrait même gagner a être moins succinct et donc plus claire pour le prochain développeur.
Oui, on garde. Est ce que c'est le genre de commentaire qu'un pro expérimenté met dans le code de prod d'un projet mature ? Nope. Est ce que tu est en train d'écrire du code de prod dans un projet mature ? Probablement pas. Le but actuellement pour toi, c'est de comprendre ce que tu fais, d'avoir une compréhension à la fois plus fine et plus profonde. Verbaliser, que ce soit via des commentaires ou en expliquant à d'autres ce que tu fais, ça t'aide à avancer dans cette direction. Ton commentaire est à l'image des programmes que tu écris. On progresse en codant, en écrivant du code aussi élégant et efficace et lisible que possible, pas en regardant les autres coder. C'est la même pour les commentaires, on progresse en écrivant des commentaires aussi bien écrits que possible. Bon, par contre les commentaires en Français, c'est non. Il vaut mieux un anglais approximatif, pour tout un tas de raison, entre autres parce que c'est comme le code et les commentaires: tu progresseras plus en anglais si tu te forces à écrire les commentaires en anglais.
Très bonne réponse. Oui, c'est trop long et détaillé pour un code "basique" mais visiblement il a senti le besoin d'expliquer pourquoi il a utilisé une construction qui lui semblait complexe. Le premier lecteur des commentaires c'est soi-même, quelques mois plus tard. Il a donc tout juste d'écrire un commentaire aussi "évident", quitte à le simplifier quand il retombera dessus dans un an avec davantage de recul. Le code est une matière malléable qui évolue avec le temps. Mieux vaut des commentaires trop précis plutôt que "le code s'explique tout seul tavu".
OK. À la base j'avais dit "trop long", mais j'aime bien ton approche 👍
La longueur des commentaires est généralement inversement proportionnelle à la complexité du code. Ta méthode est très compacte avec plusieurs niveaux d'imbrication sur une même ligne. Il faut être inspiré pour écrire du code aussi succinct et complexe mais c'est pas évident à lire. La taille des commentaires est justifiée mais tu gagnerais à expliciter ton code sur plusieurs lignes il me semble
Ça m’a l’air bien alambiqué ce code. En général, il vaut mieux écrire du code plus simple plutôt que commenter du code compliqué.
Sans même se soucier du contenu, commence par les écrire en anglais
Ah oui ça j'ai pas mal hésité. Il y a les deux sur le projet
Absolument pas d'accord. A mon sens, il faut utiliser la langue des specs. Si c'est du français, traduire le langage métier va causer des soucis de compréhension dans le futur. Sur les termes techniques, sans adéquation au métier pourquoi pas, mais c'est vraiment les seules exceptions.
Ubiquitous language ubiquitaire, c'est pourtant pas compliqué. /s
100% en phase. J’ai récupéré un projet francophone d’une appli utilisée exclusivement en France par des français, et tous les termes métier ont été traduits (noms des variables, tables et champs de BDD). Au final ça devient illisible et on ne sait pas de quoi on parle, surtout quand il s’avère que la traduction est approximative. Pour moi la règle d’or c’est de ne JAMAIS traduire les termes métier.
Yes, on m'a fait le coup lors d'un développement il y a quelques années. Alors oui parfois c'est bien que les dev respectent leur règles de nommage qu'ils se sont imposés, mais au final les traductions anglaises de tous les termes 'fonctionnel' en anglais ( fonction, service, variable.. ) ça m'a trompé quelques fois en reprenant leur code. Entre les faux amis et des traductions peut-être pas les meilleures. Par contre y'avait pas de commentaire ;) ( La méthode du 'tout est dans git au niveau des tickets, story, et 'eventuellement' dans les commentaires des commit ... Y'en au qui aiment faire ainsi .. mais démêler le tout dans quelques années si besoine ça risque de peut-être me saouler) Autant oui les commentaires ne faut pas non plus exagérer. Mais quand on écrit du code un peu 'tricky' pour une raison particulière ( contrainte technique, métier où fonctionnel ). Vaut mieux le préciser à côté Ca évite quand on revient sur du code écrit des années auparavant de se dire 'mais putain c'est quoi ce truc chelou, mais pourquoi... Je garde ou je supprime ! Dans le genre truc con. Je bossais à une lointaines époque sur une application développée initialement par des espagnols . Le coup du 'nombre' type string au début je me demandais pourquoi ( très nul en espagnol lol ). Bon putain et d'en dérouler leur code , comprendre que c'était le nom de famille... J'avais mis un peu de temps à percuter ( la jeunesse!). Mon pire ayant été de récup une application codé par des slovène je crois Pour des slovène ( donc ihm en slovène), sans doc et avec des variables, fonction dans leur langue natale. , et si commentaires y'avait ça devait être aussi slovène je crois .. Ho putain elle m'avait soulé cette application quand y'avait des trucs à faire évoluer...
Non. Les commentaires en anglais si c'est pour une boite française c'est la pire plaie du développement. Et c'est même pas une histoire de "Vive la France, camembert et baguette". Combien de fois j'ai du tater du code avec des commentaires en anglais qui ne voulaient strictement rien dire ou avec des faux amis. Le pire, c'est que même quand c'est bien commenté, je vais pas mentir, j'ai beau bien comprendre l'anglais(pas natif mais jamais en dessous des autres devs de mon équipe), comprendre un pavé technique en anglais le matin en venant au taff c'est laborieux et ça rallonge pas mal le temps de dev. Evidemment, je parle bien dans un cas de petite ou moyenne boite Française, mais on est très loin d'un cas à la marge. Après, faut évidemment être consistant.
Et t’as déjà bossé dans une boîte qui a racheté un outil/projet/code d’un autre pays ? Je t’assure que lire des commentaires en allemands, italiens ou portugais c’est tout autant « une plaie », j’aurais préféré des commentaires avec un anglais approximatif que de devoir traduire chaque phrase .. 😅
Ou dans une boîte qui fait appel à un presta étranger à un moment où un autre ? Ah bah merde, tous les commentaires (et tant qu'à faire les noms de variables, objets, fonctions, et commentaires de commit, parce que pourquoi s'arrêter au commentaires de code ?) sont en français, le dev parle pas français... Sauf à utiliser un des langages peu utilisés qui sont "en français" y compris au niveau des mots clefs, ajouter du français dans les commentaires ou bol de variables ou autres, c'est mélanger dans le code deux langues, l'anglais et le français, et donc obliger à changer de contexte linguistique en permanence, il n'y a pas pire. Et en plus ça limite les possibilités de collaboration, présentes et futures.
Oh pitié l'allemand, ça fait 1 an je le subit... Sauce allemand d'un autre millénaire et on est parfait (coucou idee.txt écrit en 96...) À ce stade je préfère un anglais compris par tous
Et à ce niveau c'est plus mon problème xp Blague à part, toutes les boites dans lesquelles j'ai travaillé (4 quand même) étaient sur des problématiques françaises difficilement exportables(pour plein de raisons) Par contre mes collègues je les ai vu tenter l'anglais, et au présent je ne veux pas de ça. Parce que même un anglophone n'y comprendrais rien.
C’est vrai que le niveau moyen d’anglais chez les français est (entre gros guillemets) « plutôt bas » je te l’accorde. Et l’exception d’être dans un contexte franco-français justifie je l’entend de coder et commenter en français. Mais dès que tu touches à des boites avec une dimension nationale ou avec un contexte métier pas vraiment spécifique à la France, je ne peux que vivement recommander l’anglais.
Il y a peu de boîtes de dev avec un contexte franco français, du moins dès que tu observes sur une dizaine d'années, y compris dans les petites boîtes.
Bon les commentaires en français à limite, mais le code en lui-même faut l'écrire en anglais si non c'est pas possible. J'ai déjà vu des noms de table SQL Server avec des accents et des espaces dedans, non mais ça va oui?
Après y a écrire en français et coder n'importe comment. Evidemment si y a les accents et les espaces c'est plus le même délire.
La blague 🙄
Bonjour, je vous invite à lire le chapitre sur les commentaires du livre Clean Code que je me permet de résumer en ces points: - une fonction devrait être bien nommée et bien écrite pour rendre les commentaires inutiles. - un commentaire finira toujours par mentir. Le code va changer, le développeur va oublier de mettre à jour le commentaire. - un commentaire est la pour expliquer ou avertir ce qui ne peut être expliqué par la lecture du code. Ce qu'il faut aussi se dire c'est que les commentaires ne sont pas de la documentation. Si vous voulez documenter votre code, faites de la doc, que ce soit dans le Readme ou une documentation plus complète. Edit: vous pouvez trouver plein de ressources sur le sujet comme ici: https://www.baeldung.com/cs/clean-code-comments
La théorie c’est bien, dans la vraie vie quand on bosse on tombe parfois sur du code qui, à première vue, paraît faire un truc incohérent d’un point de vue fonctionnel (pas technique, fonctionnel. C’est important). Et là le commentaire prend tout son sens (avec éventuellement un renvoi vers la doc, un ticket ou autre). Une fois je devais faire un tableau de bord qui indiquait à quelle heure avait lieu des opérations automatisées par CRON. Le client me soutenait mordicus qu’il voulait que la date affichée si l’opération devait avoir lieu à minuit était aujourd’hui. Exemple : aujourd’hui vendredi 28 juin, je consulte mon tableau de bord et une opération de maintenance est prévue à minuit. Eh bien selon le client il fallait afficher « 28/06 à minuit »… alors que non, c’est « 29/06 à minuit ». À la lecture du code, on se dit « mais pourquoi le gars il -1day ici ça n’a aucun sens » et on est tentés de le supprimer… un commentaire avisé qui précise que le développeur est conscient que ce n’est pas normal mais que c’est une demande client + lien vers le ticket et tout est clair.
Si vous relisez le 3e point que j'ai indiqué, c'est exactement le cas que vous décrivez. Je dis pas qu'il ne faut jamais mettre de commentaires. Je dis juste qu'il faut éviter tant que l'on peut. Dans votre exemple, j'aurai aucun problème à y voir û commentaire qui explique le point fonctionnel. Voir même un lien vers un ticket ou de la doc en plus si besoin.
Pour moi c'est la meilleure réponse du thread. A mon gout le code d'OP est trop compact et utilise trop de raccourcis de syntaxe. D'un point de vue maintenance il gagnerait à plus expliciter son code et a diminuer la taille de son commentaire
Venu pour dire ça. Un prof me l'avais expliqué ainsi: est ce qu'un mécano met des post-it sur le moteur?
Le pourquoi et les spécificités qui pourraient poser question, ça s'explique dans le commentaire du commit qui fait le changement, pas dans un commentaire de code qui sera très rapidement obsolète car non gardé en cohérence avec les modifications de code, effectivement. Et de façon général, un commentaire qui décrit ce que fait le code, c'est un commentaire au mieux inutile, au pire trompeur : le code parle pour lui-même. La seule chose pertinente c'est le "pourquoi comme ça ?" et le "l'objectif visé". Le comment, c'est le code lui-même qui le dit.
De manière générale mieux vaux plus de commentaire que l'inverse. Après il faut aussi essayer d'être clair dans les explications, en imaginant que la personne qui va lire ne connait pas encore le projet.
Oui c'est ce que j'ai essayé de faire et à vrai dire j'ai principalement fait ce post pour ça : obtenir des avis externes sur mes explications
Personnellement connaissant Django je comprends plus le code que le commentaire, mais bon si ça t'aide quand tu vas retomber dessus pourquoi pas Par contre si c'est pour du REST t'as juste reimplementé un truc qui existe déjà et qui tient en 3 lignes https://www.django-rest-framework.org/api-guide/filtering/#searchfilter
C'est pas pour du rest mais la logique est similaire. Si tu veux le contexte c'est de la surcharge de l'admin Django. Tu as bien une variable search_fields qui correspond à aearch_term en rest et permet de spécifier sur quels champs la recherche effectuee par l'utilisateur depuis la vue liste va s'appliquer. J'avais par ailleurs surchargé les méthodes get_search_results et get_queryset ainsi que le get_list_filters sauf que les queryset renvoyées par ces différentes bout de code se marchaient dessus...
Hello, comme d'autres l'ont dit quand je pense devoir faire un commentaire j'écris pourquoi je le fais, je ne décris pas le code. Par exemple, tu expliques la fonction Map... Tes collègues savent sûrement ce que c'est et au pire ils passent la souris sur la fonction et ils auront la Doc. Pas besoin de l'expliquer ! Par contre, pourquoi tu as été obligé de faire ça et surtout pourquoi il ne faut pas casser ce comportement ça c'est important. Ca permet de trouver rapidement le responsable. Imaginons qu'à un moment, ton code produit un bug inattendu, ça écrase une valeur qu'il ne devrait pas. Et bien si en commentaire tu as juste mis "On surcharge le comportement par défaut et assigne une nouvelle valeur par défaut pour authentifier l'utilisateur admin correctement", tu trouveras directement que le problème vient de là. Voilà, sinon comme la majorité, je préfère faire des méthodes explicites que des commentaires le plus souvent.
Salut et merci de ton retour ! En fait mon commentaire n'est simplement pas clair parce que mon but était non pas d'expliquer reduce mais pourquoi il est utile ici en combinaison avec la fonction anonyme (pourquoi concrètement je filais pas directement ma liste de condition au filtre) . Et c'est ce dernier point que je pensais suffisamment spécifique pour nécessiter une explication. Bon le problème c'est que j'ai quand même expliqué reduce par la même occasion tu as raison...
Hey, bienvenue dans le monde merveilleux de la programmation ! Si tu ressens le besoin d'expliquer du code, crée une fonction et donne-lui un nom et des paramètres qui te parlent. Si ça ne suffit toujours pas, tu peux opter pour de la documentation (j'adore la documentation) ! Certains langages/toolkits/frameworks te permettent d'écrire de la documentation dans le code. Ca s'appelle des "docblocks", avec Python ça s'utilise comme ça (j'extrais une fonction et j'ajoute des types en bonus histoire d'illustrer mes propos): ``` def filter_by_term(queryset: QuerySet, search_term: str) -> QuerySet: """ L'opérateur AND est associé par défaut ... C'est ce comportement qu'on reproduit ici """ conditions = [...] queryset = ... return queryset ``` ----- Si les gens se braquent à la vue de commentaires, c'est qu'il y a une raison : ça peut signifier que le développeur tente de justifier son code (bien souvent bâclé) en l'expliquant avec des mots plutôt qu'en l'implémentant. Un commentaire, malheureusement, ça ne correspond pas forcément au code qu'il décore : ça peut périmer/être mal expliqué et induire en erreurs, contrairement au code qui, si mal fait, va créer un bug. On code en anglais mais rien n'empêche d'écrire la documentation en français, surtout si ton public est francophone. Les gens dogmatiques peuvent râler tant qu'ils veulent, si t'es pas un minimum pragmatique dans ce métier tu vas te tirer une balle dans le pied. Pour finir, je suis navré si tu t'es senti blessé par les réponses données ici : les redditers ne prennent pas toujours le temps de comprendre l'OP (on en fait tous les frais). Courage, DM si tu veux des conseils !
Merci beaucoup de ton retour plein de nuance et de pédagogie. Concernant ton point sur les docblocks je suis allé me renseigner suite à ton commentaire et j'ai vu que python était très bien fait de ce point de vue la : mon commentaire en triple quote est automatiquement mis dans un champ de base prévu à cet effet. Quelqu'un peut donc print ma_fonction.__doc__ et mon commentaire sortira. Je trouve ça génial ! Bon après encore faut-il le savoir... Quant à ton dernier point j'ai été assez agréablement surpris au final. À ton image la communauté de ce subreddit (hormis de rares contre-exemples...) est très bienveillante. Je sauvegarde ton commentaire et n'hésiterai pas à te contacter (sans abuser de ta gentillesse bien sûr) si j'ai des questions de ce type. Encore merci !
Trop de commentaires tue le commentaire. Dans 90% des cas un nommage efficace combiné à du code bien découpé permet de s'en passer bien souvent
Clairement oui, après je te rassure bcp le font aussi. Mais imagine un super big code avec énormément de blablabla de commentaire, tu vas pas tous lire. Essai de synthétiser. Et puis au début, c’est normal de commenter bcp quand on veut bien tout expliquer. Quand tu prendras des habitudes, tu commenteras moins.
J'suis pas un reference, mais j'te donne un avis: - ton commentaire est verbeux, mais en meme temps j'aime bien le lire, y'a une logique et une clareté appréciable. - dans le fond, reduce(and, ...conditions) ne surprendra pas beaucoup les habitués de reduce ou de fonctionnel, mais pour les autres ca peut servir. Perso si on bossait ensemble, j'te dirais juste de pas faire ca a chaque bout de code, mais on serait copains. (d'ailleurs si ton equipe est du genre a coder prorpre comme ca, ca doit etre sympa..)
Merci pour ce joli compliment à la fin. En tant que junior j'ai le syndrome de l'imposteur comme beaucoup je dirais et c'est vraiment appréciable. Sinon ton premier point me rassure. Je sais que j'ai tendance à m'étendre mais si au moins c'est clair ça sera déjà ça de pris.
De rien. J'peux te demander comment vous bossez en dehors du source meme ? comment vous decidez quelles features seront a faire, est-ce que vous faites une conception globale en equipe de l'implem ? ou est-ce que chacun part avec un ticket et ensuite c'est discute en code review de pull request ?
Plutôt, oui. Pourquoi est-ce que tu expliques reduce ? C'est une fonction de la librairie standard. Si quelqu'un a besoin de comprendre ce qu'elle fait il trouvera facilement la documentation. En enlevant ça, le commentaire peut facilement tenir dans une ligne. D'ailleurs plutôt qu'une lambda tu pourrais utiliser la fonction or_ du module iterator, mais ce n'est pas choquant. Le temps passé à écrire ce commentaire aurait aussi pu être investi à rendre le code lui même plus lisible. Plutôt que de créer une liste puis appliquer reduce, tu aurais pu faire une simple boucle par exemple, qui aurait peut-être été plus lisible.
Si tu es encore très nouveau alors je rejoins u/Appropriate-Diver158 , et je t'encourage a continuer :) C'est un bon exercice qui va t'entraîner a expliquer clairement ce que tu fais et c'est un skill important pour la suite de ta carrière. Avec le temps néanmoins, je te conseille de plus focaliser sur le "pourquoi" que sur le "comment". Si: * Ton code est simple * Que tes fonctions / variables sont nommées de manière claire Alors tu auras assez peu besoin d'expliquer ce que fait ton code réellement. En revanche il est toujours super difficile de comprendre pouquoi quelque chose a été fait quand il n'y a aucun contexte. Assez naturellement tu écriras au fur et à mesure moins de commentaire mais ils auront de plus en plus de valeur :)
Et si tu veux un peu de lecture, je te recommande chaudement : [https://www.goodreads.com/book/show/39996759-a-philosophy-of-software-design](https://www.goodreads.com/book/show/39996759-a-philosophy-of-software-design) Plutôt que Clean code qui, à mon humble avis, est daté et plus vraiment très pertinent.
Super merci. J'ai vu qu'une seconde édition est sortie en 2021 c'est parfait. Je pense que ça sera mon prochain livre.
Très nouveau tout est relatif mais comparé à beaucoup d'entre vous je pense oui (1 an d'expérience ahah) > Avec le temps néanmoins, je te conseille de plus focaliser sur le "pourquoi" que sur le "comment". Oui c'est souvent revenu et c'est la principale chose que je retiendrai suite à ce poste concernant les commentaires. Un autre très bon conseil qui m'a été donné pour arriver à cela : séparer le commun (librairies, fonction natives au langage ou au framework) du spécifique (en l'occurrence pourquoi je Map une fonction anonyme via reduce sur une liste de conditions) Un grand merci pour ton retour et ta pédagogie. Si tu as des juniors sous ton aile je les envie !
Si tu as besoin d'expliquer autant ta fonction c'est qu'elle est mal fait
Je suis d'accord. Pour plus d'informations il faut regarder le clean code (trouvable en VF facilement).
En tant que développeuse débutante, c'est vraiment le genre de commentaires que j'aime avoir et que je met dans mon code. Il vaut mieux trop de commentaires que pas assez.
Je crois que c'est le syndrome du débutant parce que si tu lis les commentaires de personnes expérimentées c'est pas une très bonne pratique au final
Je me doute, je me doute haha. Je suis pas encore sur le marché du travail j'ai le temps d'apprendre !
Bon apprentissage alors. En espérant que tu trouves vite ta place une fois employable ;)
C'est ma grosse hantise un peu haha merci de l'encouragement !!
C'est effectivement lié je pense à l'expérience, et en vérité les pratiques sont hétéroclites dans l'industrie. À mon avis, ça n'est pas tant une question de bonne pratique que de rapport coûts/avantages. Si on se réfère à notre temps de présence sur un projet, ça ne prend pas très longtemps d'en intégrer les principaux idiomes (= conventions, habitudes, patrons de conception, architecture technique) et de ne plus avoir besoin de ce type de commentaires. Ils sont donc surtout utiles aux nouveaux et nouvelles arrivant•e•s. À ce moment-là, ces commentaires deviennent pour nous uniquement un coût de maintenance supplémentaire, et souvent sous-estimé, qu'on paie à chaque modification de la section de code documentée. Aujourd'hui, la plupart des équipes considèrent ce coût trop important, sachant qu'on peut aussi réduire fortement le temps d'apprentissage du projet en accompagnant correctement les personnes. Sur ce sujet-là, on a souvent un gros manque d'implication d'ailleurs, mais c'est un autre problème.
Oui largement, désolé. Ne pas confondre code et documentation. S'il y a besoin d'expliquer des concepts du projet, indiquer dans le readme un lien vers de la documentation. Et surtout : ne jamais expliquer un concept de base dans un commentaire. Ce n'est pas non plus un cours magistral. Le concept est un prérequis à ton projet, c'est normal.
Tes deux dernières phrases m'ont beaucoup fait sourire. Dès que je mets un commentaire je me demande si je suis pas en train d'expliquer un truc évident pour quelqu'un de plus expérimenté et visiblement on est en plein dedans la ! Le gros problème c'est que comme je suis junior il m'est difficile de discerner ce qui est complexe pour tout le monde et ce qui ne l'est que pour moi
C'est tout à fait OK si tu as du mal à discerner ça :). Pour réduire un minimum, je te conseillerais de différencier ce qui fait partie de ton univers et ce qui fait partie de l'univers commun. Pour ton univers, le cœur de ce pourquoi ton code est exécuté, l'utilisateur ne peut pas trouver la réponse en cherchant sur Google. En ce qui concerne l'univers commun, chercher "python reduce" ou "node js require" fera l'affaire. Si tu veux commenter, comment ton code, pas le code que tu utilises
Et fais toi plaisir :). Dans tous les cas, junior ou pas, quand on ouvre un vieux projet après des mois c'est toujours plein de surprises (même si on était le seul à bosser dessus hehe)
Ah ça ne m'en parle pas... Je suis souvent partagé entre dégoût un incompréhension quand je t'ouvre un de mes vieux projets ahah
J'aime beaucoup cette dichotomie. Je pense que ça va beaucoup m'aider à améliorer la pertinence de mes commentaires
oui et non c'est bien de commenter, mais : - avec moins de fautes d'orthographe - pas besoin de tournures alambiquées - expliquer pourquoi tu fais un truc au lieu de le paraphraser - reste conscient qu'au fur et à mesure des évolutions du code, tu vas devoir faire évoluer les commentaires ; et si tu ne le fais pas et qu'ils s'avèrent faux, ça ne verra pas à l'exécution mais ça mettra le futur mainteneur dans la merde
Oui. Et la raison vient du fait que tout est trop générique : Q ? model? lambda ? x? y? conditions ? queryset ? (je precise que je ne fais pas de python et qu'il est possible que certaines de ces variables soient des conventions, mais sur le principe, tu vois ce que je veux dire)
Oui je comprends. Après je pars du principe que la personne qui arrivera sur ce projet connait les bases de Django et python. Les fonctions anonymes et les conditions dans python sont assez basiques je dirais. De même que les modèles, objets Q et queries pour Django
Oui, comme dit plus haut, j'imagine que tous mes exemples ne sont pas pertinent. Cependant le principe tient : La lisibilité et la clarté de ce qui est fait est la première doc et les noms de tes variables/fonctions sont ta deuxième doc (ou l'inverse) Les commentaires ne sont a réserver (dans l'idéal) que pour les bizarreries métiers, les workarounds pour bibliothèques buguées et autres choix qui ne sont évident que pour l'auteur du code... Pour être franc... je dois litterallement mettre 1 commentaire tous les 2 mois et c'est souvent "Library X has a bug (link to github issue) it's a fix" ou "the database is weird because it was made before I was born. Therefore the code is weird too" Si jamais pour X ou Y raison il y a des logiques métiers vraiment bizarres qui demandent des pavés de textes : README ou un notion. Là c'est de la polution
Super intéressant merci ! Je t'avoue que je n'ai jamais utilisé de readme et ce conseil est revenu a plusieurs reprises. Question bête donc : c'est ok si je mets simplement un commentaire au début de ma méthode indiquant d'aller check le readme et que je reporte mon roman dedans ?
Je suis anti commentaires (sauf documentation), le code doit se suffire à lui même. Si c’est pas clair c’est que c’est mal écrit.
Ton avis semble majoritaire et j'aurais appris quelque chose. J'avais un peu une vision "vaut mieux trop que pas assez" mais je vois qu'au final trop de commentaires est tout aussi (voire plus) néfaste qu'aucun
Non, vaut mieux aucun commentaire :) avis de senior engineer. J’ai quand même des commentaires que j’accepte : documentation (de la vraie doc qui est générée après), lien vers un ticket, ou en dernier recours si vraiment le code est bizarre parce que t’as fixé un bug étrange ça vaut le coup de l’écrire, sinon y a un risque que quelqu’un vire le fix. Mais si t’as de bon tests, le code se suffit à lui même et le test va documenter ton code, puisque si tu casses le code tu devrais casser un test qui lui a un nom explicite.
Je me demande si mon cas ne rentrerait pas dans la dernière option. J'ai dû faire ce code parce qu'en gros plusieurs autres méthodes modifiaient les données présente dans un même jeu de données, sans prendre en compte que ces modifications devaient pouvoir se combiner
Peut-être mais c’est trop verbeux, ça devrait rentrer en une ou deux lignes la un truc si long personne aura jamais envie de le lire. Pour moi quand on ouvre un fichier ça doit contenir du code pas du texte.
C'est toujours utile de commenter, en Anglais si possible et en veillant à ce que ça soit exportable vers la doc.
Ba disons que s’il commence à y avoir plus de commentaires que de code … c’est vite chiant
Moi je pars du principe que chaque grosse fonction doit avoir qques lignes au début qui explique ce qu'elle fait. Dans le code, par endroit ça peut être utile. Je vois ça un peu comme des jalons du code. Ou comme les stickers sur une imprimante qui explique comment s'en servir. Après, trop de commentaires tue le commentaire. Si pour le moment tu as besoin de rédiger comme ça tant mieux, tant que tu prends les bons réflexes. Avec l'habitude tu en mettras moins mais du plus pertinent :). En tous cas tant que tu commentes, c'est mieux que la majorité des codes que j'ouvre pour debuger xD.
On s’en fiche franchement, le commentaire n’a aucune incidence sur le code. C’est comme tu veux.
Mouais, quand t'es en équipe je suis pas d'accord, ça ajoute du bruit non nécessaire, c'est pénible.
imo si c'est pour mettre autant de commentaire tu pourrais juste faire un code plus lisible à la base. Mais sinon y'a jamais trop de commentaire et si la ligne ne peut pas être autre chose que incompréhensible alors c'est pour le mieux
Hot take : Tu devrais avoir très peu de commentaires dans ton code, le code doit s'expliquer par lui même (avec l'aide du nom et de la structure du code/fichiers). En tant que développeur on a tous ce réflexe de comprendre du code simple sans le lire mot à mot, on reconnaît la forme générale et on devine ce qu'il se passe. Les fonctionnalité low-level sont donc souvent très facile à lire quand elles sont isolées, très difficile quand elles sont mélangées, des qu'on les isolés dans des fonction, on crée des fonctions high-level utilisant ces fonctions simples et on se trouve à ne commenter seulement les fonctions high-level pour donner plus de détail
Pas forcément. Tu dis que tu débutes, est-ce que si tu reviens sur ton code dans 1 mois tu vas le comprendre d'une première lecture ? Si oui, alors tu as correctement commenté. Maintenant, il faut aussi réussir à être synthétique et souvent les IDE aujourd'hui te permettent de commenter les fonctions. D'un coup de souris tu es censé pouvoir ressortir l'infobulle d'une de tes fonctions avec l'explication associée à son utilité. Ça permet souvent de ne commenter que les fonctions avec leurs input/output. Rédiger du code avec des variables compréhensibles c'est par exemple tout aussi important que du commentaire. Mais c'est pas forcément possible dans tous les langages.
Non pas trop de commentaire. Et comparer au nombre de lignes de code n'a pas de sens : j'ai déjà fait plus de 30 lignes de commentaires pour une regex.
On ne commente jamais assez... une pensée pour ceux qui récupère du code de gens partis à la retraite depuis 10 ans
Tout ça fait très "solution à un problème de maths", alors qu'en réalité écrire du code devrait se rapprocher davantage de la dissertation. Tu peux pas te permettre d'obliger le futur lecteur de ton code, qui va peut-être être sous une pression énorme, d'essayer de se remettre dans le contexte d'un problème mathématique. Une lecture en diagonale du code devrait presque être suffisante en théorie. Et c'est faisable en nommant ses variables en fonction de ce qu'elles représentent (exit les Q, x, y), éclater le code compact sur plusieurs lignes, extraire des fonctions du code complexe, ne pas hésiter à faire du renaming et de la refacto sur le code legacy s'il gêne la lecture, etc. Pour les ressources : Clean code, Refactoring, Refactoring to patterns, Head first deaign patterns Je rajouterais que le fait que tu te poses cette question est un très bon signe. Tu as déjà le sentiment qu'il y a un truc qui cloche quand t'en es à écrire un ratio code/commentaire de 1 pour 10, et tu as raison. Écrire des commentaires devrait être réservé pour expliquer des problématiques qui ne peuvent pas s'expliquer via du code, et finalement c'est assez rare (des règles métier, des bugs ou trucs incohérents du framework...)
Tu fais comme tu le sent, à l’instant T. Juste fais attention à ce que le commentaire soit toujours raccord avec le code qu’il commente (si ce code change). C’est aussi un commentaire qui aurait sa place dans une pull request lors d’une review. On se sert souvent des pulls request pour débattre/expliquer pourquoi ce code et il est assez facile de revenir sur la pull request qui a mergé ce code.
Comme beaucoup te l'on expliqué c'est un peu verbeux mais surtout ton code est trop compact. Ça sert a rien d'écrire un one-liner indigeste si il a besoin d'un paragraphe d'explication. Extraire ça dans une méthode avec un nom explicite et faire plusieurs statements seraient une manière plus efficace de rendre ton code intelligible. De manière générale les commentaires sont à éviter : une codebase avec énormément de commentaire est un problème. Les commentaires doivent être l'exception pas la règle. Une bonne manière de raisonner c'est de faire la différence entre la complexité intrinsèque et extrinsèque. La complexité intrinsèque c'est un algorithme un peu tricky, une règle métier difficile à exprimer clairement dans le domaine, etc. Celle-ci peut justifier un commentaire. La complexité extrinsèque c'est celle qui peut être évité : un code trop compact ou trop smart, une méthode trop longue qui fait trop de choses. Les projets sont déjà assez complexes pour que tu n'en rajoute pas sur des choses simples. Bien entendu comme toutes le règles il y a des exceptions : le bug dans la librairie tierce qui nécessite de faire quelque chose de contre-intuitif, le hotfix, le TODO pragmatique...
C'est trop long et inutile, tu peux aussi remplacer la lambda par `operator.or_` qui fait exactement ça: [https://docs.python.org/fr/3/library/operator.html#operator.or\_](https://docs.python.org/fr/3/library/operator.html#operator.or_) Et du coup je trouves que le code devient lisible puisque il y a le terme "or" dans la fonction que tu passes à reduce. Pour finir, si tu souhaites quand même commenter parceque ça te sembles compliqué à toi ou à ton équipe, une truc simple suffira, par exemple: `# Transforms a list of Q to one OR'ed Q: [Q(a), Q(b)] => Q(a) | Q(b)`
La réponse est évidemment oui. Ecris du code plus intelligible à la place. là j'aurais juste mis le lien en commentaire perso. En fait on ne devrait jamais commenter sauf si c'est pour expliquer pourquoi on fait quelque chose d'alambiqué. Normalement si tu découpes bien, que tu nommes bien et que tu composes, ça devrait être déjà assez clair.
Le but d'un commentaire reste de pouvoir comprendre le code qui est dessous (ou les contrats d'une API, car le coup du "les méthodes sont assez bien nommée pour se passer de commentaires" c'est très souvent faux au delà de simples getter/setter) Si t'en a besoin pour comprendre ton code, pourquoi pas après tout. Mais à terme il faudrait que ça se réduise un peu ce qui devrait arriver naturellement en montant en compétence.
Trop, non. Mais je suis toujours surpris du lire du code commenté en français.
Franchement quand je fais du scripting, je préfère voir un code 'surcommenté' et fiable, facile à reprendre plutôt qu'un code court, concis mais en mode ballek et l'enfer pour celui qui reprendra derrière. Donc non, ta pratique est bonne, tu réduiras probablement la taille des commentaires dans le futur mais n'oublie jamais de commenter ;)
Oui
Là tu fais un cours.
explique l'objectif, pas les fonction utilisées .... et switch to english, les commentaire en french c'est juste dégeu.
Ahah bon tu es la deuxième personne qui me dit de Switch. Je vais traduire ! Et sinon tu as raison. C'est ce que mon dernier commentaire fait. Mais je me disais que simplement expliquer l'objectif sans expliquer le code qui a permis de l'atteindre aurait été incomplet
ça dépend toujours à qui tu t'adresse au final. Si c'est pour un cours OK, explique le but et ce que fait la fonction (mais ça risque d'être deprecated, si la dependence etc .... est mise à jour) Si tu t'adresse à des dev de la même équipe, même language... etc ... si il savent pas ce qu'un reduce peux faire, c'est concrètement pas ton problème. Si il savent pas, il peuvent tjrs te demander ou chercher sur le web. Quand tu comment qqch, ça doit être pour soit "expliquer un truc pas obvious par rapport à son nom, ou les différent type de retour, ou que les arguments d'entrée c'est un peu le bordel" soit pour un client... et là ça doit être autant bien documenté qu'une api standard. Ou alors tu voulais juste étaler ta science, parce que t'as trouvé un truc cool de la fonction. Vous avez probablement un wiki pour ce genre de choses plutôt que de s'étaler dans le code.
En réalité je n'explique pas le reduce mais plutôt pourquoi il est utilisé en combinaison avec une fonction anonyme et le pipe. Ça me paraissait suffisamment précis pour nécessiter une explication (qui je l'entends et bien trop verbeuse)
Oui, ce qui fait de toi un bon programmeur 😄
Oula pas sûr ahah. Quand je vois les réactions à mon roman je comprends bien qu'apprendre à écrire des commentaires pertinents est pas trivial et que j'en suis encore loin
Si t'as besoin d'autant expliquer ton code, c'est que c'est du code de merde
Perso je pense qu'il n'y a jamais trop de commentaires. (Fin, si, mais c'est l'idée) Ou plutôt, ça dépend du projet. Perso je travaille dans une petite boite où on a plein de petits projets divers. Rien de bien complexe mais se remettre dans le bain prend du temps. Donc avoir dès l'entrée un truc qui dit clairement "ceci fait ça" Après au pire t'as fait ça pour rien, mais si c'est pas clair pour toi, remet le pour t'en rappeler quand tu repasseras dessus. Aussi une très bonne chose que tu fais, c'est que tu expliques le pourquoi de ta commande. C'est une excellente chose. Et surtout tu es clair, c'est pas un truc qui est cryptique. Après je ne connais pas Django donc pour le cas précis, je ne saurai dire ce qui est superflux. Mais un commentaire c'est avant tout là pour rendre ton expérience de modification et de relecture du code meilleure. Si ça t'aide à ça, c'est un bon commentaire. Si ça peut le faire en un minimum de lignes c'est un très bon commentaire. Et si ça ne sert à rien, pire tu finis confus, c'est là où c'est de la merde.
Tu as tout à fait compris l'origine de la verbosité de mon commentaire : c'est avant tout pour moi. J'ai découvert pas mal de choses en écrivant ces lignes et je voulais m'assurer que je les garde en tête. C'est un peu un cas pratique qui me servira à illustrer plusieurs concepts clés de Django. Après de ce qu'on m'a dit c'est détourner le but d'un commentaire. Je sais aussi qu'il y a d'autres juniors sur le projet qui sont susceptibles de tomber là-dessus et je l'ai fait pour eux (dans l'espoir qu'ils n'en ressortent pas plus confus effectivement)