You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository has been archived by the owner on Jan 1, 2019. It is now read-only.
This issue addresses the usage of comments/phpdocs.
comments/phpdocs should be avoided as much as possible by writing expressive code.
Don't use docblocks for methods that can be fully type hinted (unless you need a description).
Only add a description when it provides more context than the method/class signature itself. Use full sentences for descriptions, including a period at the end.
/** * This class contains methods that give the information * about what env the application is working on. * * Usage: * if ((new EnvironmentChecker())->inProduction()) { * // Do your work knowing that you are in production * } else { * // Do your work knowing that you are in development * } */classEnvironmentChecker
Bad:
<?php/* * This file is part of AlumnForce. * * (c) XXXXX <xxx@xx.com> * * For the full copyright and license information, please view the LICENSE * file that was distributed with this source code. */namespaceStripe\Model\Configuration;
/** * @category Stripe * @package Stripe * @author Nuno Maduro <nuno.maduro@mevia.fr> * @copyright 2016 Mevia * @license http://alumnforce.org Private */classRepository
Methods:
Good:
/** * @return boolean <-- Good, if you can't use type-hints. */publicfunctioninProduction()
{
returnAPPLICATION_ENV === self::PRODUCTION;
}
/** * Checks if the application is in production. <-- The method name is already understandable. * * @return boolean */publicfunctioninProduction()
{
returnAPPLICATION_ENV === self::PRODUCTION;
}
Bad:
/** * @param $something // <-- No need for this since we have the type hint. * * @return boolean // <-- No need for this since we have the return hint. */publicfunctioninProduction(string$something): bool
{
}
Comments:
Good:
// For single line comment./** * Multiline comments * should use * this format */
classCountryIsoTypeRepositoryimplementsCountryIsoTypeRepositoryContract
{
private$app; // <-- No need for Phpdocs, the constructor is explicit.publicfunction__construct(ApplicationContract$app)
{
$this->app = $app;
}
Bad:
/** * Holds an instance of the EnvironmentChecker. <-- No need for this. * * @var \Mevia\Tools\EnvironmentChecker */private$environmentChecker;
I think there is no need of going deeper on this proposal. You get the point. If something is not clear please write on the comments before voting.
The text was updated successfully, but these errors were encountered:
nunomaduro
changed the title
[WIP] Avoid redundant Phpdocs and comments
[Proposal] Avoid redundant Phpdocs and comments
Mar 27, 2018
classCountryIsoTypeRepositoryimplementsCountryIsoTypeRepositoryContract
{
private$app; // <-- No need for Phpdocs, the constructor is explicit.publicfunction__construct(ApplicationContract$app)
{
$this->app = $app;
}
This issue addresses the usage of comments/phpdocs.
comments/phpdocs should be avoided as much as possible by writing expressive code.
Don't use docblocks for methods that can be fully type hinted (unless you need a description).
Only add a description when it provides more context than the method/class signature itself. Use full sentences for descriptions, including a period at the end.
Part of this proposal was inspired in https://guidelines.spatie.be/code-style/laravel-php#docblocks
Class or interface headers:
Good:
Good:
Bad:
Methods:
Good:
Good:
Bad:
Bad:
Comments:
Good:
Class attributes:
Good:
Good:
Bad:
I think there is no need of going deeper on this proposal. You get the point. If something is not clear please write on the comments before voting.
The text was updated successfully, but these errors were encountered: