doc: Nouvel ADR pour les conventions d'architecture

[farnoux]

Document ADR pour acter les nouvelles conventions de nommage et d'architecture de nos projets Typescript.

Statut : en discussion, à faire évoluer et valider en fonction des retours.

[cparthur]

Globalement d'accord avec les propositions 👍

Juste pour le point 2 de Décision -> "kebab-case pour les noms de fichiers et dossiers".

Pour les composants réact, je les trouve plus facile à identifier lorsque le nom du fichier commence par une majuscule exemple PlansAction.tsx, je sais de suite que c'est un composant React avec du JSX.

Pour les hooks je trouve cela bizarre d'avoir use-data.ts plutôt que useData.ts, qu'en dites vous @mariheck, @marc-rutkowski ?

Sinon côté front, le challenge vient souvent lorsqu'un composant est trop gros et qu'on le scinde en plusieurs parties, comment gère-t-on l'organisation du dossier et le nom des fichiers ?

Je propose que le composant principale du dossier soit en majuscule et le reste qui n'es utilisé que dans ce dossier en minuscule (voir ici header et footer). Qu'en dites vous ?

/plansAction
    index.ts
    useData.ts
    utils.ts
    PlansAction.tsx
    header.tsx
    footer.tsx
    /axes

Aussi, j'aime bien l'idée du index.ts qui export uniquement ce qui est à exporter en dehors de ce dossier. Ce qui permet de pouvoir exporter header sans qu'il soit proposé partout dans l'app alors qu'il n'a d'utilité que localement. Ce qui permet aussi de ne plus avoir à nommer de composant comme PlansActionHeader mais simplement Header.

[farnoux]

Pour le point 2 sur les noms de dossiers et fichiers en kebab-case, encore une fois, juste un suivi des conventions existantes dans la plupart des projets open-source de la communauté TS :

Exemples (parmi de nombreux autres) :

• les hooks Mantine : https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/hooks/src
• les composants React du projet démo Vercel : https://github.com/vercel/commerce/tree/main/components

L'idée est justement d'éviter les exceptions et que ce soit le cas partout pour tous les types de fichiers (hook, composants React, etc). Donc pas du tout chaud pour avoir desfois des Majuscules, desfois des minuscules, etc.

À noter que pour un composant React, on a déjà le suffixe .tsx qui est déjà très explicite.

[cparthur]

Pour le point 2 sur les noms de dossiers et fichiers en kebab-case, encore une fois, juste un suivi des conventions existantes dans la plupart des projets open-source de la communauté TS :

Exemples (parmi de nombreux autres) :

• les hooks Mantine : https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/hooks/src
• les composants React du projet démo Vercel : https://github.com/vercel/commerce/tree/main/components

L'idée est justement d'éviter les exceptions et que ce soit le cas partout pour tous les types de fichiers (hook, composants React, etc). Donc pas du tout chaud pour avoir desfois des Majuscules, desfois des minuscules, etc.

À noter que pour un composant React, on a déjà le suffixe .tsx qui est déjà très explicite.

Pour le coup peut y avoir plein de fichiers .tsx dans un même dossier avec uniquement 1 seul composant parent exporté en dehors de ce dossier, comme l'exemple que j'ai mis. Pour ce qui est des majuscules sur les composant react JSX, ça ne vient pas de moi, je peux aussi sortir des projets qui utilisent cette convention (ex airBnb qui a largement contribué aux conventions react de manière générale). Historiquement la majeur partie des projets utilisaient cette convention, j'imagine que cela évolue. Enfin tout ça pour dire que c'est très subjectif et qu'il n'y a pas de recette magique. Perso je suis vraiment pas fan des use-hook.ts ni des /plans-action/plans-action.tsx mais si tu veux tester ça go, je voulais prendre la température des autres dev car finalement ce n'est qu'une question de préférence (l'un ou l'autre).

[farnoux]

Pour le kebab-case je comprends que ça puisse faire étrange au départ. J'ai rajouté dans la PR la raison principale de ce choix lié au suivi des conventions Next.js.

Note particulière concernant le kebab-case des dossiers et fichiers : ce choix est principalement motivé par le fait de suivre la convention Next.js (App Router), framework – et donc architecture de dossier du router associé – utilisé par la plupart de nos apps.

À titre perso pour utiliser cette convention dans mes derniers autres projets, ça rend la lecture plus simple et rapide que le camelCase, et plus de questions à se poser à l'écriture vu que tout est pareil.