[FIXED] What are the comments found above methods in a controller?

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)