@l4m3r

Полное или частичное документирование?

Нужно ли, по-хорошему, документировать очевидные вещи:
/**
  * Order model.
  * 
  * @property Car $car
  */
class Order {

  /**
     *
     * Get the car record associated with the order. 
     *
     * @return \Illuminate\Database\Eloquent\Relations\HasOne
     */
    public function car()
    {
        return $this->hasOne('App\Models\Car');
    }


Или можно пренебречь:
/**
  * @property Car $car
  */
class Order {
  /*
     * @return \Illuminate\Database\Eloquent\Relations\HasOne
     */
    public function car()
    {
        return $this->hasOne('App\Models\Car');
    }
  • Вопрос задан
  • 117 просмотров
Решения вопроса 2
DevMan
@DevMan Куратор тега PHP
заполнять имеет смысл, если потом по этим блокам генерируется документация.
если докблок сугубо для себя, то можно опустить.
Ответ написан
In4in
@In4in
°•× JavaScript Developer ^_^ ו°
Да черт его знает, с появлением 7.2 все ведь стало проще
public function car() : \Illuminate\Database\Eloquent\Relations\HasOne
    {
        return $this->hasOne('App\Models\Car');
    }

Да и IDE хорошо прослеживает типы, зависимости.

PHPDocs'ы делаю чисто по привычке, хотя смысла в них уже почти никакого.
Ответ написан
Пригласить эксперта
Ответы на вопрос 2
saboteur_kiev
@saboteur_kiev
software engineer
Я бы вместо
// * Get the car record associated with the order.

название функции переименовал бы в get_car или get_car_record
Ответ написан
@grinat
Главная проблема аннотаций в языках со слабой типизацией:
/**
* function which return dog
*/
getDog () {
return new Dog()
}

Спустя год:
/**
* function which return dog
*/
getDog () {
if ($this->temperatureInZimbabve > 30 && $this->isHuman) {
$human = new Elepant()
$human->isLeopard = $this->getAnimalType(true, false)
return $human
}
return new Beer()
}
Ответ написан
Комментировать
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы