Comment bien utiliser les commentaires dans le code WordPress : bonnes pratiques et exemples

Bien utiliser les commentaires dans le code WordPress est essentiel pour maintenir un code propre, lisible et facile à faire évoluer. De nombreux développeurs WordPress, débutants comme expérimentés, sous-estiment encore l’importance des commentaires, ce qui conduit à des thèmes et des plugins difficiles à comprendre, à maintenir ou à transmettre à d’autres équipes.

Dans ce guide complet, vous allez découvrir :

• Pourquoi les commentaires sont cruciaux dans le développement WordPress
• Les différents types de commentaires utilisables dans le code WordPress (PHP, HTML, CSS, JavaScript)
• Les bonnes pratiques pour écrire des commentaires efficaces et professionnels
• Comment documenter correctement vos fonctions et hooks WordPress avec des commentaires structurés
• Des exemples concrets appliqués aux thèmes, plugins et formulaires WordPress

1. Pourquoi les commentaires sont importants dans le code WordPress

1.1. Rôle des commentaires dans un projet WordPress

Les commentaires jouent un rôle central dans le développement WordPress, que vous travailliez sur un petit site vitrine, un thème complexe ou un plugin distribué à grande échelle. Ils améliorent la compréhension du code, facilitent la collaboration et réduisent les risques d’erreurs lors des évolutions.

• Améliorer la lisibilité du code : un code clair et bien commenté permet à n’importe quel développeur (y compris vous, dans quelques mois) de comprendre rapidement la logique métier, les traitements spécifiques et les choix techniques.
• Faciliter le travail en équipe : dans une agence, une ESN ou un projet open source, les commentaires servent de canal de communication asynchrone entre développeurs. Ils expliquent pourquoi une solution a été retenue, quelles contraintes de compatibilité ont été prises en compte, ou quels bugs historiques ont été contournés.
• Améliorer la maintenabilité : un thème ou un plugin WordPress vit souvent plusieurs années. Sans commentaires, chaque correction ou évolution prend plus de temps, augmente le risque de régression et complique la transmission du projet.
• Guider les intégrateurs et administrateurs : certains commentaires peuvent être destinés aux intégrateurs ou aux équipes support, pour préciser par exemple le rôle d’un template, le comportement d’un hook, ou les risques associés à la suppression d’un morceau de code.

1.2. Ce que doivent expliquer vos commentaires

Un bon commentaire ne décrit pas simplement ce que fait le code (ce que l’on peut souvent déduire en le lisant), mais surtout pourquoi il le fait de cette manière.

• Le contexte métier : pourquoi ce calcul, ce filtre ou cette vérification est nécessaire.
• Les choix techniques : pourquoi tel hook WordPress a été préféré à un autre, pourquoi on utilise une requête personnalisée plutôt que WP_Query dans un cas particulier, etc.
• Les contraintes : compatibilité avec une ancienne version de WordPress, prise en charge d’un plugin tiers, exigences de performance ou de sécurité.
• Les mises en garde : avertir qu’un bloc de code est critique, qu’il est lié à une fonctionnalité de paiement, ou qu’il doit rester compatible avec un thème enfant.

2. Les différents types de commentaires dans le code WordPress

WordPress s’appuie principalement sur PHP pour le back-end, mais aussi sur HTML, CSS et JavaScript. Chacun de ces langages possède sa propre syntaxe de commentaires. Bien les connaître est indispensable pour commenter efficacement un projet WordPress complet.

2.1. Commentaires sur une ligne en PHP

Les commentaires sur une seule ligne en PHP sont parfaits pour de brèves explications directement au-dessus ou à côté d’une instruction précise.

• Syntaxe : en PHP, un commentaire sur une ligne commence par // ou #, la forme // étant la plus courante dans l’écosystème WordPress.
• Usage : idéal pour préciser rapidement le rôle d’une condition, d’un appel de fonction ou d’une variable.

Exemple :

 5, 'post_status' => 'publish',
) );
?>

• Bonnes pratiques :

• Rester concis tout en étant précis : un ou deux lignes suffisent pour décrire une instruction.
• Éviter de commenter les évidences : inutile d’écrire // Incrémente i sur une ligne $i++;.
• Positionner le commentaire juste au-dessus de la ligne de code visée pour une meilleure lisibilité.

2.2. Commentaires multi-lignes en PHP

Les commentaires multi-lignes sont utiles dès qu’une explication un peu plus détaillée est nécessaire, par exemple pour documenter une fonction, une classe ou un bloc logique complexe.

• Syntaxe : un commentaire multi-lignes en PHP est encadré par /* et */.
• Usage : idéal pour décrire le rôle global d’une fonction, ses paramètres, les valeurs retournées, ou des cas particuliers.

Exemple simple :

get_row( $wpdb->prepare( "SELECT * FROM {$wpdb->users} WHERE ID = %d", $user_id ) );
}
?>

• Bonnes pratiques :

• Aligner les astérisques pour garder un bloc lisible.
• Rester synthétique : un commentaire trop long n’est plus lu.
• Placer ces blocs au début des fonctions, classes et fichiers importants.

2.3. Commentaires PHPDoc (recommandés pour WordPress)

Dans l’écosystème WordPress, l’usage de commentaires au format PHPDoc est fortement recommandé pour les fonctions, classes, méthodes, hooks et filtres. Ils permettent de générer automatiquement une documentation et de faciliter le travail avec les IDE modernes.

Exemple :

get_row( $wpdb->prepare( "SELECT * FROM {$wpdb->users} WHERE ID = %d", $user_id ) );
}
?>

Ce style de commentaire est particulièrement adapté pour documenter les fonctions personnalisées de vos thèmes et plugins WordPress.

2.4. Commentaires en HTML dans les templates WordPress

Les fichiers de thème WordPress sont principalement des fichiers PHP qui génèrent du HTML. Les commentaires HTML sont donc très utiles pour structurer les templates et aider les intégrateurs à s’y retrouver.

• Syntaxe : un commentaire HTML est encadré par .
• Usage : idéal pour délimiter les grandes sections d’une page, préciser le rôle d’un bloc ou rappeler qu’un élément est lié à un hook ou à un modèle particulier.

Exemple :

Attention : ces commentaires peuvent être visibles dans le code source HTML du site côté navigateur. Évitez donc d’y placer des informations sensibles (chemins internes, configurations spécifiques du serveur, détails de sécurité, etc.).

2.5. Commentaires en CSS pour les styles de thème

Les feuilles de style d’un thème WordPress (notamment style.css) acceptent des commentaires spécifiques permettant de documenter à la fois le thème lui-même et chaque section de style.

• Syntaxe : comme en PHP, les commentaires CSS utilisent /* ... */.

En tête de style.css, un bloc de commentaire particulier décrit le thème :

/*
Theme Name: Mon Thème WordPress Personnalisé
Theme URI: https://exemple.com/mon-theme
Author: Mon Agence Web
Author URI: https://exemple.com
Description: Thème WordPress sur mesure optimisé pour les performances et le référencement.
Version: 1.0.0
Text Domain: mon-theme
*/

Plus bas dans la feuille de style, vous pouvez structurer vos sections :

/* Typographie globale */
body { font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
} /* En-tête du site */
.site-header { background-color: #111; color: #fff;
}

2.6. Commentaires en JavaScript pour scripts front-end WordPress

Les thèmes et plugins WordPress modernes intègrent souvent du JavaScript (voire du React dans l’éditeur de blocs). Les commentaires JS suivent la même logique que ceux en PHP :

• Single-line : // Mon commentaire
• Multi-line : /* Mon commentaire sur plusieurs lignes */

Exemple :

// Gère l'ouverture et la fermeture du menu mobile
const menuToggle = document.querySelector('.menu-toggle');
const menu = document.querySelector('.main-navigation'); if (menuToggle && menu) { menuToggle.addEventListener('click', function { menu.classList.toggle('is-open'); });
}

3. Bonnes pratiques pour écrire des commentaires efficaces en WordPress

3.1. Être concis mais descriptif

Un bon commentaire va droit au but. Évitez les formulations vagues comme :

« Cette fonction fait quelque chose. »

Préférez une explication précise :

« Cette fonction calcule le score de l’utilisateur à partir de ses actions récentes (commentaires, likes, partages). »

3.2. Éviter les redondances avec le code

Un commentaire n’a pas vocation à répéter exactement ce qui est déjà évident dans le code. Par exemple :

// Incrémente le compteur
$counter++;

n’apporte aucune réelle valeur si la variable est déjà bien nommée. Concentrez-vous sur les points réellement utiles : décisions métiers, règles complexes, comportements inattendus, contraintes liées à des hooks WordPress précis, etc.

3.3. Commenter les blocs logiques, pas chaque ligne

En développement WordPress, il est plus utile de commenter les blocs fonctionnels entiers (boucles de requête, hooks, validations de formulaire, intégration avec des API, etc.) plutôt que chaque instruction.

Par exemple, dans un template :

 3, 'post_status' => 'publish', 'meta_key' => '_is_featured', 'meta_value' => 1,
) ); if ( $featured_query->have_posts ) : while ( $featured_query->have_posts ) : $featured_query->the_post; get_template_part( 'template-parts/content', 'featured' ); endwhile; wp_reset_postdata;
endif;
?>

3.4. Mettre à jour les commentaires avec le code

Un mauvais commentaire, obsolète ou trompeur, est pire que l’absence de commentaire. Lorsque vous modifiez une fonction, pensez systématiquement à relire et à actualiser son commentaire.

• Si vous changez la signature d’une fonction, mettez à jour les @param et @return dans le bloc PHPDoc.
• Si une fonction ne fait plus exactement ce qui est décrit, ajustez la description.
• Supprimez les commentaires devenus inutiles.

3.5. Utiliser une langue cohérente

Choisissez une langue de référence pour vos commentaires (français ou anglais) et utilisez-la de manière cohérente dans tout le projet. Dans un environnement international ou open source, l’anglais est souvent privilégié ; pour un projet interne à une équipe francophone, des commentaires en français peuvent être plus pertinents.

4. Comment bien commenter des exemples concrets dans WordPress

4.1. Expliquer une fonction personnalisée dans un plugin

Voici une version corrigée et correctement commentée d’une fonction de récupération de données utilisateur, à intégrer dans un plugin ou un thème :

Les commentaires expliquent ici à la fois le rôle global de la fonction et certains choix techniques (utilisation de l’API get_user_by plutôt qu’une requête SQL pure, par exemple).

4.2. Commenter une boucle WordPress pour les articles récents

 5, 'post_status' => 'publish', ) ); // Parcourt les articles et affiche leur titre foreach ( $recent_posts as $post ) { echo '
' . esc_html( $post['post_title'] ) . '
'; } // Libère la mémoire occupée par la variable wp_reset_query;
}
?>

Les commentaires décrivent la finalité de la fonction, la logique de la requête et le comportement attendu dans le template.

4.3. Commenter la validation d’un formulaire dans WordPress

Dans un plugin ou un thème, la validation des formulaires est un lieu stratégique pour les commentaires, car les règles métiers et de sécurité y sont souvent nombreuses.

Les commentaires mettent ici l’accent sur la sécurité (vérification du nonce) et sur la logique métier (champs obligatoires, envoi d’email).

4.4. Commenter la personnalisation d’un thème via un hook

Voici un exemple corrigé et commenté d’une personnalisation de thème :

Le commentaire global permet de savoir rapidement à quel moment ce code s’exécute et dans quel but (personnalisation du thème).

4.5. Commenter la procédure d’activation d’un plugin

Lors de l’activation d’un plugin, il est courant de créer des tables personnalisées ou d’initialiser des options. Voici une version corrigée et commentée de ce processus :

prefix . 'monplugin_table'; $charset_collate = $wpdb->get_charset_collate; // SQL de création de table utilisant dbDelta (important : structure spécifique) $sql = "CREATE TABLE {$table_name} ( id INT(11) UNSIGNED NOT NULL AUTO_INCREMENT, name VARCHAR(255) NOT NULL, description TEXT NOT NULL, date DATETIME NOT NULL, PRIMARY KEY (id) ) {$charset_collate};"; // Crée ou met à jour la table dbDelta( $sql );
}
register_activation_hook( __FILE__, 'monplugin_activate' );
?>

L’ancienne version contenait l’erreur db Delta. Elle est ici corrigée avec dbDelta, et les commentaires expliquent le rôle de chaque étape : chargement de upgrade.php, définition du SQL, utilisation de dbDelta.

5. Commentaires et bonnes pratiques spécifiques à l’écosystème WordPress

5.1. Documenter les hooks (actions et filtres)

WordPress repose massivement sur les hooks. Les commenter clairement est essentiel pour que d’autres développeurs puissent les utiliser, les surcharger ou les étendre.

Les développeurs qui liront ce code sauront immédiatement quel hook est utilisé, ce qui est modifié et dans quel contexte.

5.2. Commenter les templates pour les thèmes enfant

Dans un thème destiné à être étendu par un thème enfant, les commentaires HTML et PHP peuvent servir de guide aux développeurs qui souhaitent surcharger certains templates.

 
> 
 
 
 
  

            
            

                

                    
                    Commentaires
                
                
                
                

                    
                
                
                
                

                    
Laisser un commentaire
                    

                        
                        

                            

                                Nom *
                                
                            
                            

                                Email *
                                
                            
                        
                        

                            Message *
                            
                        
                        

                            
                            Votre commentaire sera soumis à modération avant publication.
                        
                        
                            
                            Publier le commentaire
                        
                    
                    

                
            
            
            
            
            

5.3. Commentaires, performances et sécurité

Les commentaires sont ignorés par le moteur PHP lors de l’exécution. Leur impact direct sur les performances est donc généralement négligeable, surtout par rapport aux bénéfices en termes de maintenabilité.

En revanche, certains points de vigilance s’appliquent :

• Ne pas mettre de mots de passe, clés API ou informations sensibles dans les commentaires, même côté serveur.
• Éviter les détails trop techniques dans les commentaires HTML visibles dans le code source côté navigateur, qui pourraient donner des indications aux attaquants.
• Ne pas compter sur un commentaire pour « documenter » une mesure de sécurité : le code doit rester le véritable garant de la sécurité.

6. Structurer et standardiser les commentaires dans vos projets WordPress

6.1. Définir des règles internes de commentaires

Pour les équipes qui gèrent plusieurs sites WordPress, il est pertinent de définir un standard interne :

• Type de commentaires à utiliser pour les fonctions, classes, hooks et templates.
• Langue de référence (français ou anglais).
• Niveau de détail attendu : par exemple, obligatoire sur toutes les fonctions publiques d’un plugin.
• Structure des commentaires PHPDoc (balises @param, @return, @since, etc.).

6.2. S’inspirer des standards officiels de WordPress

WordPress propose des recommandations de style de code (PHP, JavaScript, CSS) accompagnées de directives sur la manière de commenter. S’inspirer de ces standards vous aidera à produire un code familier à toute la communauté WordPress, plus simple à reprendre par d’autres développeurs.

6.3. Utiliser les commentaires pour améliorer la qualité globale du projet

Enfin, les commentaires peuvent vous servir de balises pour suivre l’état du code :

• Utiliser des marqueurs comme @todo dans un bloc de commentaire pour signaler une amélioration future.
• Indiquer lorsqu’un bloc de code est temporaire ou doit être supprimé à une date donnée.
• Préciser lorsque du code est conservé uniquement pour la rétrocompatibilité avec une ancienne version de WordPress ou de PHP.

En combinant ces bonnes pratiques avec une écriture de code claire, vous obtiendrez des projets WordPress à la fois robustes, évolutifs et simples à reprendre, quelles que soient la taille de l’équipe et la durée de vie du site ou du plugin.