99% of phpdoc comments are a complete waste of time
Permalink 2 users found helpful
It seems the move to 5.7 is including more phpdoc comments. Yet so much work on comments is a waste of time and even harmful.
I am not against comments. I like well commented code. I like to think that my own code is well commented compared to most. I like to think that the comments I add to code are meaningful and useful to both myself and others who may use that code in the future.
So why am I picking on phpdoc?
The fashion in phpdoc is to write some comments that repeat the interface to a function so it can be extracted. Hence these comments duplicate information that can already be read from the function declaration in the code. Such comments are worse than useless. They are actually harmful. When the code is subsequently changed, the duplicate declaration of the interface in phpdoc needs to be kept in synchronisation with the function they are repeating the interface for. Get out of step and they create mis-information. So we have work being spent on duplicating information that subsequently creates more work keeping that worthless duplicate synchronised.
I like the idea of automatically generating API documentation from code. I want to see more of it. But it desperately needs to be useful. To add explanation. To add meaning. To make things easier for those that follow. The current fashion for duplicating an interface in a different syntax using phpdoc is completely the opposite.
If I wanted to pull out the interfaces to functions I would use grep to pull out the real interface. Where comments are used to provide inline API documentation, they need to provide something I can't get from grep and reading a few lines of code.
I am not against comments. I like well commented code. I like to think that my own code is well commented compared to most. I like to think that the comments I add to code are meaningful and useful to both myself and others who may use that code in the future.
So why am I picking on phpdoc?
The fashion in phpdoc is to write some comments that repeat the interface to a function so it can be extracted. Hence these comments duplicate information that can already be read from the function declaration in the code. Such comments are worse than useless. They are actually harmful. When the code is subsequently changed, the duplicate declaration of the interface in phpdoc needs to be kept in synchronisation with the function they are repeating the interface for. Get out of step and they create mis-information. So we have work being spent on duplicating information that subsequently creates more work keeping that worthless duplicate synchronised.
I like the idea of automatically generating API documentation from code. I want to see more of it. But it desperately needs to be useful. To add explanation. To add meaning. To make things easier for those that follow. The current fashion for duplicating an interface in a different syntax using phpdoc is completely the opposite.
If I wanted to pull out the interfaces to functions I would use grep to pull out the real interface. Where comments are used to provide inline API documentation, they need to provide something I can't get from grep and reading a few lines of code.
Agree with all these reasons andrew posted. At the same time I see JTF's concerns, where there are PHPDocs that are as simple as something like this:
could be considered just extra work for someone else to have to go maintain after a change, and it provides no extra value.
That said, I do think that if it adds any value whatsoever, such as describing that that parameter is expected to be a string and/or giving a description as to what the format of $r is supposed to be, it is worthwhile to have the whole doc there, for "IDE niceness" as it's being called.
Example of something I would consider a worthwhile PHPDoc even for as simple as it is:
This at the very least lets the developer know without digging into the function that $r is supposed to be a string, and that it is either an int or a boolean value that is returned. While there is a lot of room to improve on, it does provide some immediate benefit.
/** * @param $r * @returns mixed */ public function doWork($r){ ... }
could be considered just extra work for someone else to have to go maintain after a change, and it provides no extra value.
That said, I do think that if it adds any value whatsoever, such as describing that that parameter is expected to be a string and/or giving a description as to what the format of $r is supposed to be, it is worthwhile to have the whole doc there, for "IDE niceness" as it's being called.
Example of something I would consider a worthwhile PHPDoc even for as simple as it is:
/** * @param string $r * @returns bool|int */ public function doWork($r){ ... }
This at the very least lets the developer know without digging into the function that $r is supposed to be a string, and that it is either an int or a boolean value that is returned. While there is a lot of room to improve on, it does provide some immediate benefit.
Without seeing an example of what you mean here's my 1.5 cents:
- It's a very concise way of exposing important information. i.e `@returns int|string` is quicker to write and read the equivalent in english.
- It requires more developer discipline, and developer discipline in frameworks is a good thing.
- In my experience writing @param & @return tags generally helps the me think more about the API design rather than just whacking a method here and there.
- For those of us who use IDEs like PHPStorm phpdoc actually makes code completion useful.
- Code completion rocks.
- They also allow quick documentation popups in IDEs. I.e. cursor on a method, hit the short cut and read the docs with all the params & return values.
- Quick documentation popups rock.
- There's more IDE niceness but it'll get boring.
So from my perspective
- @param, @returns, @throws, @deprecated etc are more useful than nothing.
- Adding intent is best (as long as it's in a standardised form)
- Concrete5 should have a documentation standard with examples for typical usages. Documentation standards have been around for a looooong time. Pick one and copy it.
Cheers