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

Question

[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');
    }

Comments

[Артём]

Излишек комментариев тоже не хорошо

Answer 1

[DevMan]

заполнять имеет смысл, если потом по этим блокам генерируется документация.
если докблок сугубо для себя, то можно опустить.

Comments

[l4m3r]

А если, скажем, это open-source либа для github?

[DevMan]

l4m3r, а что не понятно в коде из одной строки без документации?

[l4m3r]

DevMan, да всё понятно. Речь лишь идёт о некой "кошерности" и best practice. Что-то типа "всё обязательно должно быть документировано, иначе говнокод".

[DevMan]

l4m3r, никакой связи между опенсорсом, гитхабом и "кошерностью" не существует.
на том же гитхабе есть валом кода без документации вообще.

документация по использованию проекта, желательно с примерами, намного важнее документирования очевидных вещей "для галочки".

Answer 2

[Виталий Инчин ☢]

Да черт его знает, с появлением 7.2 все ведь стало проще

public function car() : \Illuminate\Database\Eloquent\Relations\HasOne
    {
        return $this->hasOne('App\Models\Car');
    }

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

PHPDocs'ы делаю чисто по привычке, хотя смысла в них уже почти никакого.

Comments

[l4m3r]

Хм. А это мысль.

[l4m3r]

Лень проверять. Навскидку не подскажешь: если вместо
return $this->hasOne('App\Models\Car');
использовать
return $this->hasOne(Car::class);

Будет ли autoload Car, даже если метод car() не используется?

[Виталий Инчин ☢]

l4m3r, навскидку, должен бы

[Артём]

l4m3r, Car::class === 'App\Models\Car'

Удобство Car::class в том, что через его референс можно сразу открыть этот класс.

А автолоад работает совсем не так.

[l4m3r]

Артём, это я понимаю. Вопрос был, что если явно объявляешь ClassName::, он не подгружается, если не используешь?

[Виталий Инчин ☢]

l4m3r, должен подгрузится)

Answer 3

[Saboteur]

Я бы вместо
// * Get the car record associated with the order.

название функции переименовал бы в get_car или get_car_record

Comments

[l4m3r]

Сейчас бы в PSR не уметь!

Answer 4

[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()
}