Nume relevante, nu comentarii inutile!

Nume relevante, nu comentarii inutile!

Mă enervează la maxim Docblocks. Sunt comentariile alea de la începutul fiecărei metode, funcții, fișier sau variabilă care adaugă zgomot de fond. E atât de mult zgomot încât IDE-urile sunt configurate by default să le ascundă.

Nu mă înțelege greșit, apreciez documentația bună și Dockblocks reprezintă un mod decent de a explica parametri și alte minuni, dar unele chestii sunt ridicole. De-a dreptul ridicole! (ca să nu mai spun că, de obicei, comentariile devin irelevante)

Poate că atunci când adăugăm un docblock nu ar trebui să facem din asta un proces mecanic, ci unul căruia îi acordăm puțină atenție. Poate că un nume sugestiv pentru o variabilă sau metodă este mai util decât un comentariu care, mai devreme sau mai târziu, va fi out of sync în raport cu bucata de cod. Poate…


Dacă introducem în discuție și unelte de genul phpcs, care te forțează să adopți un anume stil, lucrurile devin hilare. De exemplu, phpcs pentru WordPress te obligă să adaugi un comentariu la începutul fiecărui fișier în care spui ce face acel fișier. Și ajungem în situații mișto de genul:

formatting.php:

<?php
/**
 * Main WordPress Formatting API.
 *

media-template.php

<?php
/**
 * WordPress media templates.
 *

(da, știu că WP nu e cel mai bun exemplu, dar dacă cu asta lucrez…)

Adaugă un comentariurăspuns pentru

Link-urile în context sunt binevenite. Comentariile fără nume/email valid sunt șterse.
PS: Comentariul NU este editabil.

Acest sit folosește Akismet pentru a reduce spamul. Află cum sunt procesate datele comentariilor tale.

Site-ul blog.iamntz.com utilizează cookie-uri. Continuarea navigării presupune acceptarea lor. Mai multe informații.

windows apple dropbox facebook twitter