PHPDoc style commentaar overbodig?

Home » Artikelen » PHPDoc style commentaar overbodig?

In de wereld van webontwikkeling is heldere en gedetailleerde documentatie van je code van onschatbare waarde. Een van de meest effectieve manieren om dit te bereiken is door het gebruik van PHPDoc-stijl opmerkingen. In dit artikel zullen we dieper ingaan op wat PHPDoc-stijl opmerkingen zijn, waarom ze belangrijk zijn en bespreken we enkele nuances met betrekking tot het documenteren van parameters en retourwaarden in PHP 8.

Wat zijn PHPDoc-stijl opmerkingen?

PHPDoc-stijl opmerkingen zijn speciale commentaren die je rechtstreeks in je PHP-code kunt opnemen om informatie te verstrekken over de functionaliteit, parameters en retourwaarden van functies en methoden. Ze volgen een gestandaardiseerd formaat en kunnen worden geëxtraheerd en weergegeven met behulp van tools zoals PHPDocumentor.

Waarom zijn PHPDoc-stijl opmerkingen belangrijk?

Het toevoegen van PHPDoc-stijl opmerkingen aan je code heeft meerdere voordelen:

• Duidelijke Documentatie: Ze bieden leesbare documentatie voor andere ontwikkelaars (inclusief jezelf) om snel te begrijpen hoe een specifieke functie of methode werkt.
• Code Autocompletie: PHPDoc-stijl opmerkingen kunnen IDE's en code-editors helpen bij het bieden van automatische aanvullingen en suggesties terwijl je code schrijft, waardoor je efficiënter kunt werken.

Documenteren van parameters en retourwaarden in PHP 8

Met de introductie van PHP 8 zijn er verbeteringen aangebracht in het documenteren van parameters en retourwaarden. In veel gevallen is het expliciet specificeren van deze informatie in PHPDoc-stijl opmerkingen niet langer nodig, aangezien PHP 8 beter in staat is om deze informatie uit de code zelf af te leiden. Dit betekent dat je vaak de parameters en retourwaarde in PHPDoc-stijl kunt weglaten, waardoor je code schoner en minder repetitief wordt.

class test
{
	/**
	* test uitleg
	* @return array
	* @param $var string
	*/
	public function __construct(string $var):array
	{
		return [$var,$var];
	}
}

In het bovenstaande voorbeeld zijn de regels @param en @return overbodig.

Conclusie

Hoewel PHPDoc-stijl opmerkingen een goede gewoonte blijven voor het documenteren van je code, is het belangrijk om te begrijpen dat in PHP 8 het expliciet specificeren van parameters en retourwaarden in veel gevallen overbodig kan zijn. Dit bespaart tijd en vermindert de kans op inconsistenties tussen de documentatie en de daadwerkelijke code. Het is echter nog steeds waardevol om andere aspecten van je code te documenteren, zoals de doelstelling van een functie, mogelijke uitzonderingen en gebruiksinstructies, om de leesbaarheid en begrijpelijkheid te verbeteren.

PHPDoc tags uitschakelen in phpstorm

Om je phpdoc tags uit te schakelen in phpstorm kun je gaan naar: Settings > Editor > File and Code Templates > Includes > PHP Function Doc Comment Hier kun je aangeven hoe je phpdoc code eruit moet komen zien.