Why (in our time) always write phpdoc comments?

For the second office, where they demand everywhere to write phpdoc comments, and in fact it's kind of useless writings authored by K. O.:

/**
 * Class FloatToStringConverter
*
 * Converts float value to string with specific precision
*/
class FloatToStringConverter
{
/**
 * Default precision
*/
 private const DEFAULT_PRECISION = 2;

/**
 * @var int
*/
 private int $precision;

/**
 * FloatToStringConverter constructor.
*
 * @param int $precision
*/
 public function __construct(int $precision = self::DEFAULT_PRECISION)
{
 $this->precision = $precision;
}

/**
 * @param float $value
 * @return string
*/
 public function convert(float $value): string
{
 return (string)round($value, $this->precision);
}
}


What information will be lost if you remove the phpdoc? No. While writing a review takes time, and they create visual noise and make code hard to read.

Question: why use comments everywhere, if the code is self-documenting, and they are needed only in exceptional cases when there is not enough language features - type type hint float|int, collections/arrays string[], Type[]?

In 2 times it is easier to read:

class FloatToStringConverter
{
 private const DEFAULT_PRECISION = 2;

 private int $precision;

 public function __construct(int $precision = self::DEFAULT_PRECISION)
{
 $this->precision = $precision;
}

 public function convert(float $value): string
{
 return (string)round($value, $this->precision);
}
}
April 7th 20 at 15:31
7 answers
April 7th 20 at 15:33
Solution
@isaias21,
My question is not about the comments in the client code, namely about the PHP Doc blocks for classes and their members, because for some reason they are often considered the de facto standard.

Duplication types in php do not need the docks and no standard is not(unless internal-corporate).

PS And Yes, if programmers at least sometimes, before something zayuzat asked myself, why they do it, and whether there are ways to do things better, industry development-would have been quite different.
Now checked - the last phpDocumentor reads all pieces of the PHP 7.4, up to typed properties. So duplication of these data totally meaningless. - Leslie commented on April 7th 20 at 15:36
April 7th 20 at 15:35
  • Not always the things that seem like self-documenting code is to be perceived the same after a while.
  • Whatever good code, a simple sentence with a description for what purpose you need this property easier than looking for it from across the room.
  • It is necessary to generate documentation. In which not only the names of properties and methods, but also their descriptions. In Russian, if needed.
  • If the project comes to a beginner, it is easier to understand with documentation.
  • Some IDE can show you the tips and additional info from phpdoc


You like it or not, documentation is extremely important. May require to comment on everything, from the point of view of the company, a little unnecessary. But it might help in future refactoring when the code is a little out of control. It is a restriction that is inconvenient for the programmer, but keeps him from being shot in the leg.

But, this is all true in cases where the comments represent a little more than
/**
 * @var int
*/
private int $precision;
And a little more than

/**
 * @var int Precision
*/
private int $precision;


Just write that the Converter converts a property called precision contains the precision value is foolish.

And it turns out that you need to comment ONLY where I have something to add to semidocumentary. - Leslie commented on April 7th 20 at 15:38
@isaias21, In small classes, Yes, it looks redundant. But as time goes on. There are different tasks with different requirements. Sometimes you need a short time to cram some kind of feature to extend a class, it would seem quite self-documenting method. Several other antipatterns and two years later, looking at the code, you can understand what he's doing, but it is absolutely not clear why.

Again, in my opinion, the corporate requirement to comment on each method, I think it is not a bad way of hedging. To go back to the method which was written two years ago, could anyone clear language to read why this is here.

But the comments of the
/**
 * @var int Precision
 */

be useless and absolutely do not meet this requirement

P. S - robb42 commented on April 7th 20 at 15:41
April 7th 20 at 15:37
If you write only classes of conversion from number to string, document them, really, no reason.
In the normal work of a class is the adapter between the logic levels where a method is a statement of a higher level, and its content refers to lower. So even after reading the text method, you will understand what he is doing, but do not understand - why and which section of the business logic this action generally applies. And then - comment the first line! Of the coder, who drummed in your head that you have to comment everything, and the only reason he took the trouble to do it here, too.
In short it is for dumb coders) - Leslie commented on April 7th 20 at 15:40
@isaias21is up to you after the next flight of thought did not have to justify why you code harder to follow than a stupid coder. - veda.Hessel72 commented on April 7th 20 at 15:43
April 7th 20 at 15:39
There are interesting companions: __call(), __get() and __set() which give interesting magic and headache-free php-doc
It is also an exceptional case, and it does not justify documenting everything. - Leslie commented on April 7th 20 at 15:42
April 7th 20 at 15:41
I do not remember where I read the phrase, but I like it. "Comments, this apology programmer unreadable code." Documenting any difficult decisions necessary, but not all in a row.
My question is not about the comments in the client code, namely about the PHP Doc blocks for classes and their members, because for some reason they are often considered the de facto standard. - Leslie commented on April 7th 20 at 15:44
April 7th 20 at 15:43
If the Doc generated by the code are published, this can be the meaning of
The generator can't read the type-hinting phpspy? - Leslie commented on April 7th 20 at 15:46
@isaias21for mixed enumerations do not have. - sheridan.Jacobs commented on April 7th 20 at 15:49
April 7th 20 at 15:45
To move the cursor to method and read what it does and for what its parameters are. Well, in most cases it's just a standard code, or comply with, or are not working.

Find more questions by tags PHP