What are the comments found above methods in a controller?

Riley Goodman 0
Viewed 24

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.

oop php laravel
1 Answers

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):

enter image description here

Additionally, if I go to use this method, I get some help:

enter image description here

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.

Tim Lewis0
Related