Documenter Ses Scripts

[jojo]

Vous savez comme il est important de documenter ses scripts. Cela permet :

• de vous relire plus facilement
• de vous rappeler ce que vous avez fait et pourquoi
• aux autres de comprendre ce que vous avez fait si vous les partager, et ainsi d'augmenter leur niveau de compétence.

La manière la plus connue est :

-- remettre les bons horaires

ou

for j = i+1, i+119, 17 do -- parcourir les jours

La mise en commentaires peut également être utile pour désactiver une partie de code en développement, sans en perdre la source :

--    for k = j+1, j+16, 4 do -- parcourir les partir de jour

Mais vous pouvez également mettre en commentaire plusieurs lignes successives, sans devoir mettre -- au début de chaque ligne.

Pour cela encadrez les lignes de --[[ (au début) et --]] (àla fin)

--[[      for l = k+1, k+3 do
        HPvalue = l  -- valeur de la propriété
        HPparameter = Parameters[l-k] -- nom de la propriété
        jsonInput = ('"properties":{"'..ConfigHP[HPday]..'":{"'..ConfigHP[HPpart]..'":{"'..HPparameter..'":'..ConfigHP[HPvalue]..'}}}')
        fibaro:debug(jsonInput)
        HC2:PUT("/api/panels/heating/" ..HPid, jsonInput)
      end --]]

[Steven]

Steven
> Le problème des commentaires sur un langage interprété est que le commentaire doit être interprété, donc traitée par le processeur bien qu'il ne fasse rien.
> Un commentaire en LUA est donc une utilisation du temps processeur pour rien du tout ....
 
Tous
> Steven TA GUE.....
> On s'en fiche des perfs nous ce qu'on veux c'est comprendre le script .
  
Steven
> Oui mais l'optimisation n'est pas ...
  
Tous
> On t'a dis de te taire NON ?

Steven
> OK OK, si vous insister ..


Plus sérieusement :
JE SUIS 1000% D'ACCORD, il faut abuser des commentaires peut importe les performances.

Au travail, j'essaie toujours de décrire "en français" ce que je vais coder. Ce me permet de préparer mon cerveau à  ce que je vais coder et parfois voir qu'il manque des informations ou que cela n'est pas cohérent. Dans mon cas, j'ai 10 secondes entre le moment ou je décrit en français et le moment ou je code. Au delà  de ces 10 secondes, j'ai déjà  oublié ce que j'ai précédemment décrit. C'est le bénéfice de l'age ... hein @mprinfo 

Autre exemple, il y a 2 semaines, j'ai repris le code d'un collègue (malade). J'ai mis 1.5 semaines à  comprendre son code non documenté   et j'ai effectué la modification demandée en 2 jours. Sacré perte de temps. A sa décharge, il n'avait pas prévu de tomber malade. Mais les commentaires s'écrivent AVANT le code.

 

 

En tout cas .. merci jojo ... pour cette piqà»re de rappel.