Issue
This may be a silly question, but I'm new to back-end development.
I always see comments like this above various methods:
/**
* Display a listing of the resource.
*
* @return \Illuminate\Http\Response
*/
public function index()
{
// ...
}
What are these called? Do they even have a name? Does the @return actually do anything, or is it just for reference?
I'm mostly asking because I have a technical interview as a junior Laravel developer coming up this week, and I want to make sure all my code is up to standards for a pair-programming session they said might happen.
Solution
These are called "DocBlocks", or Documentation Block Comments, etc. You can read more about them here:
https://docs.phpdoc.org/guide/getting-started/what-is-a-docblock.html
https://docs.phpdoc.org/guide/guides/docblocks.html
Basically, these are a way to summarize what a Method/Function does, expects as its arguments (if any), and what it returns. IDEs/Code Editors like VSCode, Sublime Text, PHPStorm, etc. can actually read these comments and assist you when using them, providing hints, autocompletion, etc.
Here's a basic example:
<?php
namespace = App\Http\Controllers;
class ExampleController extends Controller {
/**
* Method accepts an instance of `MyModel` and returns
* a View responsible for displaying associated information
*
* @param MyModel $myModel - An instance of `MyModel`
*
* @return \Illuminate\Contracts\View\View
*/
public function myMethod(MyModel $myModel) {
return view('index', compact('myModel');
}
}
With this comment in place, my instance of VSCode (or your IDE of choice), should be able to display some information when hovering (or similar):
Additionally, if I go to use this method, I get some help:
As you can see, VSCode now knows what myMethod
is, what it expects and returns, how to use it, etc. They aren't strictly required, as some IDEs can auto-detect methods, arguments and returns, but they can help.
Answered By - Tim Lewis Answer Checked By - Robin (PHPFixing Admin)
0 Comments:
Post a Comment
Note: Only a member of this blog may post a comment.