Aller au menu - Aller au contenu

[Plan du site] Vous êtes ici --- > Le Site du Zéro > Les forums > Site Web > PHP > Règles de rédaction d'un tuto PHP > Lecture du sujet

Règles de rédaction d'un tuto PHP

Pour une bonne lecture et une bonne compréhension

Vous devez être inscrit pour pouvoir poster des messages

Page : 1  2  Suivante
Auteur Message
1 visiteur sur ce sujet (1 anonyme)
Page : 1  2  Suivante
Hors ligne Tortue facile # Posté le 06/10/2007 à 22:40:50
Explorateur de FTP
Avatar
Admins
Amis codeurs bonsoir :D

Les plus assidus d'entre vous auront remarqués que les validateurs viennent de réorganiser les tutos PHP, et par la même occasion ont fait le ménage parmi les tutos. Il s'avère que la présentation des codes est assez disparate est qu'on a du bon et du moins bon.

En clair, tous ceux qui sont en train d'écrire un tuto de PHP sont priés de respecter les consignes ci-dessous, quand à ceux qui ont déjà leur tuto en ligne, je les invite à les relire et à les mettre aux nouvelles normes.

Par ailleurs les tutos PHP n'expliquant ou ne donnant qu'un simple script ne seront plus acceptés, n'hésitez pas à demander à un validateur si vous n'êtes pas sur, envoyez nous le lien de votre tuto par mp pour qu'on puisse vous donner une réponse satisfaisante.

Règle de rédaction d'un tuto


  • Un code indenté.
  • les balises <?php et ?> dans tous les scripts pour activer la coloration syntaxique.
  • Nom de variable explicites.
  • Commentaires dans les codes.
  • or die (mysql_error()) à la fin de chaque requête.
  • Protection contre les injections SQL (intval pour les nombres et mysql_real_escape_string pour les données.


L'indentation du code



Afin que les codes soient lisibles, ces derniers doivent être parfaitement indentés.
Code : PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<?php
while($donnees = mysql_fetch_assoc($requete))
{
    if($donnees['id'] == 1)
    {
        echo 'Valide';
    }
    else
    {
        echo 'Non valide';
    }
}
?>

Les balises <?php et ?>



Pour activer la coloration syntaxique, tout code PHP doit commncer par un <?php et finir par un ?> (même pour une ligne).
Mauvais
Code : PHP
1
2
3
$jour = date('d');
echo 'Aujourd\'hui, nous sommes le : '.$jour;
?>


Bon
Code : PHP
1
2
3
4
<?php
$jour = date('d');
echo 'Aujourd\'hui, nous sommes le : '.$jour;
?>


Nom des variables explicites



Bon là c'est clair, on évite les noms de variables incompréhensibles.

Commentaires dans les codes


Citation : Règle de la maison IBM
Si après avoir lu uniquement les commentaires d'un programme vous n'en comprenez pas le fonctionnement, jetez le tout !

Je crois que tout le monde comprend, en lisant les commentaires, on doit pouvoir savoir à quoi sert ce dernier, mais le contraire n'est pas à faire : trop de commentaires tue le commentaire, seul les commentaires qui appuient sur un point précis (nom de la fonction, explication d'un condition, etc) sont indispensables, le reste c'est dans le tuto.

or exit (mysql_error()) à la fin de chaque requête



Dans le forum PHP, beaucoup trop de Zéros oublient de mettre ceci à la fin de leur requête, et lorsqu'il y a une erreur ils ne comprennent pas d'où ça vient.
Code : PHP
1
2
3
<?php
$retour = mysql_query('SELECT * FROM news ORDER BY id') or exit (mysql_error());
?>


Protection contre les injections SQL



Pour les données numériques :
Code : PHP
1
2
3
<?php
$page = intval($_GET['page']);
?>


Pour les données textuelles :
Code : PHP
1
2
3
<?php
$titre = mysql_real_escape_string($_POST['titre'])
?>


Si vous avez des idées n'hésitez pas à les rajouter.
Édité le 04/07/2008 à 13:24:58 par Tortue facile
 
Hors ligne bluestorm # Posté le 06/10/2007 à 22:53:33
dont ask to ask
Avatar
Groupe : Membres
Très bonne initiative !

Dans l'ensemble, je trouve les conseils donnés tout à fait louables, à l'exception de celui sur les commentaires. Cette citation est paradoxale, car on penserait plutôt à
Citation
Si après avoir lu uniquement le code d'un programme vous n'en comprenez pas le fonctionnement, jetez le tout !


Si je peux rajouter une petite remarque, il pourrait être bon de rassembler ces "bonnes pratiques PHP" et de les mettre dans un tuto, un peu plus détaillé, vers lequel vous pourriez renvoyer les membres. Je pense que ce genre de contenu (une fois que la phase de rédaction, qui peut impliquer les membres, et donc a sa place sur le forum, est achevée) a plus sa place parmis les tutos.
 
Hors ligne Obli # Posté le 07/10/2007 à 00:19:21
Avatar
Groupe : Membres
Bons conseils, cela donnera une structure uniformes aux divers tutos.

Cela dit, la structure sera peut-être trop uniforme, je veux parler ici de l'indentation. Il en existe plusieurs types, certains privilégiant l'aération du code (celui indiqué), d'autres cherchant plutot à condenser le code afin d'éviter de prendre 7 lignes pour un simple if...else , etc etc.

Et c'est comme ça que l'on apprend, en voyant les habitudes des autres, les tutos ne servent pas simplement à comprendre comment marche tel ou tel sujet, ils font bien plus, ils apprennent à coder, à structurer son code, car souvent rédigés par des auteurs compétents. Or, si l'on uniformise tous les styles de code, le charme est perdu, je trouve ça dommage.

Il serait plus juste de limiter l'indentation à un style "correct, clair et structuré selon des regles propres mais précises et respectées", du moment qu'il n'y a pas de fantaisie, je trouve ça mieux, cela donne une touche plus personnelle.
Hors ligne Thunderseb # Posté le 07/10/2007 à 00:35:12
gg nextmap !
Avatar
Validateurs
Ces conseils seront ajoutés dans le tuto Conseils des validateurs (voir mon profil pour le trouver) ;) Dans ma version pour le tuto, précise que le style d'indentation n'est pas important (BSD/Allam ou K&R..) : l'important c'est que ce soit indenté. Dans le tuto, des remarques sur le code HTML seront aussi présentes ;)
Édité le 07/10/2007 à 00:36:36 par Thunderseb
 
Hors ligne Obli # Posté le 07/10/2007 à 01:00:47
Avatar
Groupe : Membres
Je disais cela pour l'indentation, mais on peut généraliser, "ajouter un 'or die(mysql_error())' " devrait se transformer en "gérer les erreurs sql d'une façon ou d'une autre", il y a des méthodes plus élégantes syntaxiquement :)

Enfin, on est d'accord sur le fond du moins ^^
Hors ligne anonymousguest # Posté le 07/10/2007 à 13:33:25
I'm the Dude
Avatar
Groupe : Membres
Salut,
je suis plutôt d'accord avec ces recommandations dans l'ensemble mais il y en a une qui me dérange un peu :
Citation : Tortue facile
Pour activer la coloration syntaxique, tout code PHP doit commncer par un <?php et finir par un ?> (même pour une ligne).

Je ne conteste pas le <?php puisqu'il est nécessaire pour la coloration syntaxique mais pourquoi faudrait-il forcément terminer par un ?> ?
Il n'est pas nécessaire en php si on ne compte rien afficher par la suite et je ne le mets d'ailleurs jamais pour éviter d'afficher un espace par distraction (ce qui peut être ennuyeux lorsqu'on utilise les cookies ou la fonction header()).
De plus, c'est déjà assez lourd d'avoir 2 lignes de code à la place d'une seule, pas la peine d'en rajouter.

Bibles : PHP - MySQL - REGEX - REGEX² - XHTML - CSS
Pas bible : gestion des erreurs
 
Hors ligne Tortue facile # Posté le 07/10/2007 à 13:47:45
Explorateur de FTP
Avatar
Admins
Salut,

Pour ce qui est du commentaire d'Obli, oui il y a toujours mieux pour gérer les erreurs SQL mais sauf si c'est le but d'un tuto je préfère que l'on mette ça car quand les Zéros copieront/colleront le code, ils auront le message comme quoi ils ont un problème avec leur requête et ça permettra d'éviter les topics du genre "mon mysql_fetch_assoc marche pas".

Sinon, je comprends parfaitement le point de vue de anonymousguest, la balise ?> n'est pas indispensable pour la coloration syntaxique mais si je demande la mettre c'est pour faire plus propre (c'est le but de ces règles).
On n'en tiendra pas rigueur si ces balises de fermeture sont absentes.

Toutes ses règles sont bien sur à modérer, on va pas refuser un tuto juste parce qu'il manque un <?php ou un oubli d'indentation dans un paragraphe, on est pas non plus des sadiques.
 
Hors ligne Cam # Posté le 07/10/2007 à 22:32:51
Have fun !
Avatar
Newsers
Citation : Tortue facile
Dans le forum PHP, beaucoup trop de Zéros oublient de mettre ceci à la fin de leur requête, et lorsqu'il y a une erreur ils ne comprennent pas d'où ça vient.

En effet, d'ailleurs j'ai fait un topic recensant les erreurs les plus fréquentes en PHP / SQL, vous pourriez vous en servir de référence au besoin (le lien est dans ma signature). Et sinon, bravo pour l'initiative car encore aujourd'hui je regardais un tuto où les codes PHP n'étaient pas colorés. ;)

Image utilisateurImage utilisateurImage utilisateur
À la recherche d'un développeur (bénévole) PHP/MySQL avec une bonne expérience pour un projet novateur. Si vous êtes intéressé, contactez-moi par MP.
 
Hors ligne Aravis # Posté le 09/10/2007 à 20:42:59
apt-get install Windows
Avatar
Groupe : Membres
Comment on indente son code dans un texarea ?
Hors ligne WaR TeaM # Posté le 09/10/2007 à 20:47:11
La mort doit être vécu !
Avatar
Groupe : Membres
Tu utilise le bouton "espace" ou sinon tu indente sur notepad++ et quand tu copie/colle, le code est indenté normalement ;)

Voilà ++

Codeur PHP/SQL
Image utilisateur
 
Hors ligne anonyme # Posté le 09/10/2007 à 20:49:31
Groupe :
Citation : Aravis
Comment on indente son code dans un texarea ?

Sinon si tu utilises firefox il y a aussi l'extension Tab In Textarea qui permet de mettre des tabulations directement dans un textarea.
Hors ligne The fan of Charlotte # Posté le 14/10/2007 à 15:35:45
There're many who couldn't ...
Avatar
Groupe : Membres
oui avec les nouvelles règles les tutos seront plus lisibles ;)

"There were many who couldn't understand, and sometimes he walked among them. But even in his darkest hours, he knew in his heart, that someday it would return to him. And his world would be whole again. And his belief in god and love and art would be reawakened in his heart."

Lucas Scott, ep 16 season 5, OTH

 
Hors ligne Aravis # Posté le 15/10/2007 à 07:50:27
apt-get install Windows
Avatar
Groupe : Membres
Les tabulations sont géante sur le site je trouve c'ets tres laid.

Des espace par deux a chaque niveau ca va ?
Hors ligne Truffaut # Posté le 15/10/2007 à 11:12:38
Groupe : Membres
Tant que les mêmes règles d'indentions sont respectées dans tout le code, je suppose que c'est bon (même si 2 espaces c'est un peu ric-rac non ?) :)
Hors ligne The fan of Charlotte # Posté le 16/10/2007 à 16:46:08
There're many who couldn't ...
Avatar
Groupe : Membres
moi ce qui me genait le plus avant c'était l'indention ;)

"There were many who couldn't understand, and sometimes he walked among them. But even in his darkest hours, he knew in his heart, that someday it would return to him. And his world would be whole again. And his belief in god and love and art would be reawakened in his heart."

Lucas Scott, ep 16 season 5, OTH

 
Hors ligne the angel # Posté le 22/10/2007 à 07:09:27
Avatar
Groupe : Membres
Salut,
Je voulais préciser pour les erreurs de requêtes SQL :
Il serait peut-être intéressant de privilégier le exit plutôt que le die dans ce topic au moins.
En effet, die est un alias de exit et la documentation déconseil l'utilisation des alias puisqu'il peuvent disparaître d'une version à l'autre sans préavis.

Biensûr je ne parle pas de le mettre en tant que règle de validation, car les règles deviendraient trop loudes à force.
Mais de le mettre correctement dans les topic de se genre qui servent de référence, à force de le voir sa devrait rentré chez les zéros :) .
Hors ligne max 2000 # Posté le 23/12/2007 à 12:57:04
Qui ne tente rien n'a rien.
Avatar
Groupe : Membres
plutôt que or die(mysql_error()) (qui est très bien)

il faudrait mettre

or die('Erreur SQL à la ligne ' . __LINE__ . ' <br /> '. mysql_error());

ceci afin de savoir d'où vient son erreur :)

(c'est une bonne habitude à prendre alors autant la généraliser non?)

Image utilisateur
 
Hors ligne Nelty # Posté le 26/12/2007 à 19:43:23
Vieux motard que j'étais...
Avatar
Groupe : Membres
Salut Tortue,

Alors que mon tutoriel venait d'être mis en ligne, je devais déjà le mettre à jour :p .
Un validateur me l'a refusé parce que mes codes XHTML n'étaient pas valides. Je pense qu'il serait intéressant de préciser ça dans ce post-it, parce que je ne le savais pas du tout qu'il fallait que les codes XHTML soient valides...







Python



À l'ouïe de ce mot, vous pouvez penser à deux choses. La première, c'est le serpent. La deuxième, c'est le langage de programmation. Étant donné que nous sommes sur un site basé autour de ce dernier domaine, je vais plutôt m'intéresser au langage. :p

Concrètement, Python c'est quoi ?



Python est comme je l'ai indiqué plus haut un langage de programmation interprété.
Il est placé sous une licence libre et est un langage dit «multi-plateforme» (il fonctionne sous Windows, Mac et Linux).
Comme beaucoup, il est à la base exploitable en console, mais l'utilisation de GUI est envisageable pour faire une application graphique.

Atouts



Un des gros avantages de Python est qu'il est très simple à l'écriture et vous permet d'adopter de bonnes méthodes de programmation, notamment au niveau de la lisibilité du code.
En effet, ici, plus d'accolades ou autres pour indiquer un bloc d'instruction (if, else, while, ...), tout se fait par indentation.
Ainsi, un tel code en PHP :
Code : PHP
1
2
3
4
5
6
<?php
for($i=1;$i<=3;$i++)
{
echo $i*2.' ';
}
?>

Donnera ceci en Python :
Code : Python
1
2
3
4
for i in xrange(1,4):
  print 2*i
# ou
[i*2 for i in [1,2,3]]


Les deux afficheront (à peu près) :
Citation : Résultat :

2,4,6


Remarquez la simplification du code pour effectuer une action très simple.

Il a aussi l'avantage d'intégrer de nombreuses bibliothèques pour effectuer une multitude d'actions très diverses, dans tous les domaines. math pour les opérations mathématiques par exemple.

Pour finir, il est aussi exploitable sur le Web. Pour l'utiliser, il vous faudra un hébergeur l'acceptant et peut-être inclure certaines bibliothèques selon vos besoins (je pense à CGI pour les traitements de formulaire). À titre d'information, alwaysdata accepte le Python et est gratuit.

Où apprendre ?



Question évidemment indispensable si vous êtes intéressés... La première, la plus évidente, c'est la documentation officielle de Python, malheureusement uniquement disponible en anglais.
Mais il existe un cours très réputé rédigé par un certain Gérard Swinnen qui est disponible en français.
S'il ne vous plaît pas, Google (ou autre moteur de recherche) est votre ami !

Où se faire aider ?



Peut-être une question qui ne vous viendra pas à l'esprit immédiatement, mais quand vous aurez un problème que vous ne saurez résoudre... Ne vous inquiétez pas, d'autres gens sont passés avant vous et sont prêts à vous aider !
Dans un premier temps, je vous conseille de passer sur IRC, channel #python, serveur irc.epiknet.org . Vous y trouverez un petit groupe de gens qui pourront peut-être vous aider.
Après, si vous n'avez pas résolu votre problème, il reste le forum « Autres langages » où des Pythoneux viennent de temps en temps.
Enfin, si votre problème est lié à l'utilisation d'une bibliothèque, n'oubliez pas d'aller consulter sa documentation (très souvent en anglais).
 
Hors ligne mrLou # Posté le 13/03/2008 à 19:43:34
Cherchez... vous trouverez.
Avatar
Groupe : Membres
Bonjour à tous.
Si je peux me permettre une petite remarque.
Il faudrait éviter dans le rédactionnel les phrases du genre:
- c'est très simple
- c'est très facile
- il faut simplement
- il n'est pas difficile
- etc.
Même si c'est la vérité, ce genre de formulation revenant à traiter les gens qui ne comprennent pas, d'idiots ou de crétins congénitaux ce qui, à la longue, fini par les dégouter à jamais d'apprendre par eux même.
On peut trouver, facilement :) :p , une façon neutre de l'exprimer tout en restant très vivant comme le sont les tutos du Zéro.
Amicalement.
mrLou

Image utilisateur
 
Hors ligne Dev-master # Posté le 21/03/2008 à 09:37:28
Webmaster/programmeur
Groupe : Membres
Merci pour toutes ces règles. ;)
 
Hors ligne raphamil # Posté le 20/05/2008 à 13:11:04
Avatar
Groupe : Membres
Citation : the angel
Salut,
Je voulais préciser pour les erreurs de requêtes SQL :
Il serait peut-être intéressant de privilégier le exit plutôt que le die dans ce topic au moins.
En effet, die est un alias de exit et la documentation déconseil l'utilisation des alias puisqu'il peuvent disparaître d'une version à l'autre sans préavis.

Biensûr je ne parle pas de le mettre en tant que règle de validation, car les règles deviendraient trop loudes à force.
Mais de le mettre correctement dans les topic de se genre qui servent de référence, à force de le voir sa devrait rentré chez les zéros :) .


J'allais le signaler :)

(\__/)
(/¤.¤\) <= Lapinator ! ^^
('')|('')
Exécuter plusieurs fonctions au chargement d'une pageUne horloge temps réel grâce à Javascript (nouveau) • Séparer le comportement de la strucure (bientôt) • Chercher plus rapidement dans la doc Qt
72.73% apple-geek
 
Hors ligne Neoterranos # Posté le 21/05/2008 à 00:38:11
Oh my god, they killed Kenny !
Avatar
Groupe : Membres
Citation : Nelty
Salut Tortue,

Alors que mon tutoriel venait d'être mis en ligne, je devais déjà le mettre à jour :p .
Un validateur me l'a refusé parce que mes codes XHTML n'étaient pas valides. Je pense qu'il serait intéressant de préciser ça dans ce post-it, parce que je ne le savais pas du tout qu'il fallait que les codes XHTML soient valides...

Je lis ça et je constate que certains tutos comportent des codes invalides...
Surprenant ^^
Édité le 21/05/2008 à 00:40:38 par Neoterranos

Image utilisateur
Perdu sur le SdZ ? Clique ici ! Perdu sur CCDS ? Clique ici !
 
Hors ligne rga # Posté le 29/05/2008 à 11:33:05
Elle veut ma mort
Avatar
Groupe : Membres
Citation : Tortue facile
Les plus assidus d'entre vous auront remarqués que les validateurs viennent de réorganiser les tutos PHP, et par la même occasion ont fait le ménage parmi les tutos. Il s'avère que la présentation des codes est assez disparate est qu'on a du bon et du moins bon.

Ouh la faute... :p Je rappelle à tous qu'ici, c'est plutôt 'et' car 'il s'avère que la présentation des codes est (verbe) assez disparate et (conjonction de coordination) qu'on a du bon et du moins bon.'

Sinon, c'est clair que certains sujets (tutos ou forums) oublient fréquemment les balises définies par le site et qui sont pourtant essentielles à la compréhension.

PS: Si je n'ai pas hésité à corriger cette faute, c'est parce que le site nous demande d'avoir une orthographe et une grammaire correcte... N'est-ce pas, Tortue facile ?
Hors ligne rommani_te # Posté le 06/06/2008 à 12:06:57
Avatar
Groupe : Membres
Bonjour à tous.
je veux seulement dire merci.
Hors ligne luc@s # Posté le 18/08/2008 à 13:42:17
PPHP
Avatar
Groupe : Membres
Bon le or die(mysql_error()) c'est uniquement pour débugger hein !
C'est un peu bête de l'utiliser en phase de production
pour la sécurité et l'ergonomie.
Donc ce n'est pas une bonne pratique, je suis désolé...

Code : PHP
1
2
3
4
5
<?php
if(!rtfm()) {
    exit();
}
?>
 
Hors ligne Arnich # Posté le 19/08/2008 à 11:48:37
Point trop n'en faut
Groupe : Membres
Une regression suite a une modification du shéma de la base peu arrivé en prod, si les or die sont resté l'erreur sera plus rapide a détecté et l'utilisateur qui aura vu l'erreur sera plus clair.
Hors ligne luc@s # Posté le 19/08/2008 à 13:53:13
PPHP
Avatar
Groupe : Membres
C'est sûr si les tests n'ont pas été faits en local, et/ou que l'appli est mal conçu... :lol:
Dans ce cas on retarde la mise en production.
Moi je l'utilise qu'en cas de debug, çà me va, jamais eu de soucis.

Code : PHP
1
2
3
4
5
<?php
if(!rtfm()) {
    exit();
}
?>
 
Hors ligne Talus # Posté le 27/08/2008 à 23:50:16
タルス
Avatar
Groupe : Membres
Personnellement, je l'utilise tout le temps... Mais si le mode débug est activé, j'ai alors la précision qu'il apporte. Sinon, juste un message d'erreur type "Erreur SQL #RUB_XX" (ou RUB est l'endroit ou s'est produit l'erreur (Activation, Forums, ....), et XX le numéro de la requete)
 
Hors ligne luc@s # Posté le 28/08/2008 à 14:18:34
PPHP
Avatar
Groupe : Membres
Citation : Talus
Personnellement, je l'utilise tout le temps... Mais si le mode débug est activé, j'ai alors la précision qu'il apporte. Sinon, juste un message d'erreur type "Erreur SQL #RUB_XX" (ou RUB est l'endroit ou s'est produit l'erreur (Activation, Forums, ....), et XX le numéro de la requete)


Et pourquoi ne pas enregistrer le mysql_error() dans des logs ?
error_log(mysql_error())
Tu fais pas chier l'user et tu as quand même ton msg d'erreur

Code : PHP
1
2
3
4
5
<?php
if(!rtfm()) {
    exit();
}
?>
 
Hors ligne Talus # Posté le 28/08/2008 à 16:21:16
タルス
Avatar
Groupe : Membres
Parce que ca me fait chier de consulter les logs.
 

Retour au forum "PHP" ou à la liste des forums

Vous devez être inscrit pour pouvoir poster des messages

Changer de design | En savoir plus | Plan du site | Politique d'accessibilité | Règles | RSS tutoriels | RSS news
Édité par Simple IT SARL : Nous contacter | Notre blog | Revue de presse | Publicité

Y'a plus rien à lire, faut remonter maintenant !

Hébergement web - Correction de tutoriels - Créer un site
Vous souhaitez apparaître ici ? Contactez-nous.

Nombre de connectés 151 Zéros connectés | Requêtes SQL 7 requêtes | Temps de génération de la page : Total (SQL) 0.116s (0.097s)