Documentation pour les grands ou petits projets avec PHP?

Question

nous parlons beaucoup de la documentation pour les programmeurs dans le moment. Comment gérez-vous cette partie?

Quelle est la meilleure méthode pour introduire un nouveau type d'équipe dans un "grand" projet PHP. De quoi a besoin un nouveau type?

Mes pensées à ce jour:

• bon code source
• documentation api générés par phpdoc
• style de codage clair/directive

Une sorte de papier/wiki .. avec des informations sur l'infrastructure (base de données, firewalls ..)

Quoi d'autre fournissez-vous si vous devez remettre votre projet à quelqu'un d'autre (possible pas aussi bon que vous en PHP) ..

Vous créez quelque chose comme "pour ajouter une fonction pour lire les données du serveur, mettre dans le modèle xYZ? "

désolé pour mon pauvre anglais :)

Answer 1

Vous devriez envisager d'utiliser tous les trois d'entre eux. Cependant, n'essayez pas de compliquer votre documentation: plus il est difficile de la tenir à jour, plus elle risque de ne pas être maintenue. À mon humble avis, le strict minimum pour introduire une base de code à un nouveau programmeur est une ligne directrice de codage (comment appeler vos variables, comment appeler vos classes, utilisez-vous la notation hongroise?) Et phpdoc. Si votre code utilise fortement des bibliothèques tierces et un fichier de configuration volumineux, écrivez un petit PDF qui couvre les étapes pour que votre code fonctionne sur une nouvelle machine.

Si vous utilisez des tests unitaires, n'oubliez pas de documenter ceux-ci également.

Même dans ces cas, attendez-vous à des appels téléphoniques fréquents après avoir abandonné votre code à un nouveau codeur. Ce qui semble logique et clair pour vous n'est probablement pas pour le nouveau gars.

Answer 2

Si le projet a des API alors probablement je fournirais des exemples d'utilisation, des exemples etc. en plus des autres.

Answer 3

La documentation est bonne - mais pensez-y comme un guide. Il ne devrait pas être écrit pour enseigner la programmation et il ne devrait pas être un document qui est facilement écrit périmé.

La seule chose dont j'ai toujours eu besoin quand je rejoins un nouveau projet est de savoir où se trouve le code et comment y accéder. L'association de lignes de code à un environnement de développement ou de mise en scène fonctionnel ouvre rapidement la porte à l'expérimentation et à la découverte du «modèle» des développeurs précédents.

Si je peux faire de petites modifications dans une interface, alors j'ai craqué l'écrou et peut commencer à travailler en arrière vers les données.

Mais j'ai l'habitude de venir à bord de projets qui ont peu ou pas de documentation. Tout le monde n'est pas à l'aise avec ça.

Answer 4

Je code pour une base de code de taille moyenne qui est presque entièrement le produit du travail de l'autre programmeur (je suis le nouveau type).Nous avons une documentation auto-embellie à partir des commentaires de l'API phpdoc et des fichiers texte de meilleures pratiques en contrôle de version. J'abandonnerais les deux pour: des commentaires en ligne plus détaillés et des tests automatisés.

Je trouve généralement la documentation api utile pour créer de nouvelles fonctionnalités, mais pas particulièrement utile pour la recherche de bugs, ce qui ne serait vraiment bien expliqué par les commentaires en ligne. Donc, dans mon propre travail, j'essaie d'exposer le comportement du nouveau code dans les commentaires avant de toucher les lignes de code. Je veux aussi passer à Test Driven Design, mais je n'y suis pas encore parvenu. Oui, je suis un codeur compétent, mais la taille et la complexité de la base de code et le fait que la plupart du code a été créé par quelqu'un d'autre signifie que je dois souvent lui demander des explications sur les sources potentielles de bogues. Donc, si vous êtes vraiment occupé à faire vivre le code après avoir déménagé, pensez à vous rendre disponible en tant que ressource si vous le pouvez.

Une dernière chose que je considère essentielle est git (ou mercurial, ou un autre D.V.C.S.), pour l'historique de validation documentative et le potential web-interface au code qui peut venir avec eux.