Comment or real code

I saw the code below during surfing.

/** @var SplFileInfo[] $files */

What does the code above mean?
It seems a comment because it starts with “/*”.

But the part of the code below looks a real code.

[]

At first I thought it is a comment since the quote below is comments.

Maybe this helps:

var declarations, wherever they occur, are processed before any code is executed. … The scope of a variable declared with var is its current execution context, which is either the enclosing function or, for variables declared outside any function, global.

var - JavaScript article

It would help if a link to the script was shown.

I usually test for results by using the following:

<?php 
declare(strict_types=1);
error_reporting(-1);
ini_set('display_errors', '1');

echo '<br>' .__line__;
/** @var SplFileInfo[] $files */
echo '<br>' .__line__;
echo '<br>' .__file__;
die;

What you posted is called an annotation.

1 Like

Was your post meant for me, joon1 or igorb45?

I believe the concern is the double asterisks
/**
compared with common documentation examples

/* 
this is a multiline comment 
*/

In other words, what looks code-like @[]$ might be a comment?

For me, it looks more like information than code, but anyway…

The “C style” comment is used in various languages and AFAIK there is no standard that applies to all. I have seen comments like what is seen in documentation examples and others with “extra” asterisks. The code was fine so I assume it’s OK to do. It feels like it might be insignificantly wasteful. Once the parser sees a “/*”, every time it sees another “*” does it enter a conditional needlessly waiting for the “/” instead of moving along?

1 Like

It’s a docblock to help editors that understand them, like PHPStorm. For your example it means that $files is an array (denoted by []) of SplFileInfo objects. So when you loop over the array with foreach in PHPStorm will suggest with methods you can call on each object.

Other tools, like PHPStan can also use them to check if you’re using your code correctly. When you have the annotation in your example and try to assign hello (string) to $files PHPStan will complain (rightfully) that a string is not an array of SplFileInfo objects.

5 Likes

It would be useful to add that PHP itself does not read those annotations and will not error when you put something in the variable that is not in line with the docblock.

For PHP itself they’re just regular comments.

1 Like

@rpkamp is correct. There is more to annotations as well. Another use is in generating documentation with phpDocumentor
https://www.phpdoc.org/

Here is an example of generated documentation from phpDocumentor
https://demo.phpdoc.org/Responsive/

From the Wiki

PHPDoc is an adaptation of Javadoc for the PHP programming language. It is still an informal standard for commenting PHP code, but it is in the process of being formalized.[1] It allows external document generators like phpDocumentor, which is the de facto standard implementation,[1] to generate documentation of APIs and helps some IDEs such as Zend Studio, NetBeans, JetBrains PhpStorm, ActiveState Komodo Edit and IDE, PHPEdit and Aptana Studio to interpret variable types and other ambiguities in the loosely typed language and to provide improved code completion, type hinting and debugging.

PHPDoc supports documentation of both object-oriented and procedural code.

2 Likes
<?php 
declare(strict_types=1); 
error_reporting(-1); 
ini_set('display_errors', '1'); 
echo '<br>' .__line__; 
/** @var SplFileInfo[] $files */ 
echo '<br>' .__line__; 
echo '<br>' .__file__; die;

The result of the code above is the following.

1 Like

I don’t understand clearly about annotation.

Ah, it’s “C style” comment.

To add onto what @benanamen and @rpkamp said, PHP Code Sniffer is a great tool that checks for this kind of annotation.