Programmation PHP/Commentaires

Programmation PHP

• Introduction
• Installer PHP
• Composer
• IDE
  • PhpStorm
  • NetBeans
  • Eclipse
  • Visual Studio Code
• Bases du langage
  • Commentaires
  • Premier programme
  • Variables
  • Variables superglobales
  • Constantes
  • Opérateurs
  • Fonctions
  • Tableaux
  • Structures de contrôle
  • Boucles
• Programmation avancée
  • Dates
  • Sessions
  • Cookies
  • Cache
    • Memcached
    • Redis
  • Formulaire
  • Fichiers
    • Objets COM
    • Images
  • Mails
  • Sécurité
  • Programmation orientée objet
  • Bases de données
    • Microsoft SQL Server
    • MySQL
    • PDO
    • SQLite
  • Expressions rationnelles
  • Code de haute qualité
    • Analyse statique de programmes
  • Exceptions
  • Xdebug
  • Mots réservés
• Apprendre par l'exemple
  1. Utilisation de variables
  2. Un sommaire simple
  3. Interaction avec un formulaire
  4. Afficher le résultat d'une requête BDD
  5. Modifier une table
  6. Faire un livre d'or
  7. Faire un mini forum de discussion
  8. Parser avec DomXml
  9. Coder en MVC
  10. Faire un webservice
  11. Vérification RIO
  • AJAX
  1. Sommaire en Ajax
  2. Mise à jour périodique d'un cadre
  • Mini CMS
  1. Introduction
  2. Développement
     • Les couches choisies
     • Code de service
     • Modélisation
     • Implémentation
     • La vue
     • Ajaxification
     • Premier noyau
     • Fournir les données
     • IHM
  3. Rétrospective
  4. Conclusion
• Extensions PHP
  • cURL
  • DOMDocument
  • JSON
  • MING
  • SPL
• Bibliothèques externes
  • ADODB
  • DOMPDF
  • FPDF
  • PHPExcel
  • PHPMailer
  • PHPWord
  • RabbitMQ
• Cadriciels
  • CakePHP
  • PEAR
  • Symfony
  • Frameworks de tests
    • PHPUnit
    • SimpleTest
    • Behat
• Logiciels métier
• Problèmes connus

Principe

Les commentaires sont en réalité des portions de texte qui ne seront pas interprétées par PHP et ne seront visibles que dans le code source. Ils jouent un rôle très important dans la réalisation et la mise à jour d'un script : en effet, les commentaires rendent le code plus lisible et peuvent aider les éventuelles personnes qui souhaitent retravailler votre script.

Il existe trois façons différentes d'ajouter des commentaires à son script PHP :

1. La méthode avec les symboles // pour ajouter un commentaire sur une ligne.
2. La méthode avec le sigle # pour ajouter un commentaire sur une ligne également.
3. La méthode avec les caractères /* */ pour désigner un bloc de commentaires.

<?php
# un commentaire PHP

// encore un commentaire PHP

/* et encore 
   un 
   autre, 
   mais sur plusieurs lignes cette fois-ci ! */

Il est important de ne pas emboîter les commentaires. Exemple à ne pas suivre :

<?php
    /*blabla /* hihi*/ blalbal*/

L'interpréteur comprendra que le commentaire s'arrête à hihi*/ et il tentera d'interpréter blalbal*/. Il en résultera donc une erreur.

Standardisation des commentaires

Les commentaires sont très utiles aux programmeurs, mais se révèlent surtout indispensables lors de travail en équipe. Il existe en outre des logiciels qui génèrent une documentation complète à partir des commentaires insérés dans le code du programme. De là est apparue une certaine forme de standardisation de ceux-ci afin de faciliter la génération de documentation. On peut en effet ajouter des commentaires structurés pour permettre de générer une documentation automatique via PEAR ou phpDocumentor. Exemple :

/*
* Commentaires sur le rôle du fichier courant
*
* date modifier : 13 mars 2013
* @since 13 mars 2013
* @author Prénom Nom (courriel)
* @copyright PHPascal.com
* @version 1.2
*
*/

Les commentaires ainsi interprétés (ex : variables après arobase) sont appelés des annotations.