On 1/7/21 11:25 AM, Tom Rini wrote:
On Thu, Jan 07, 2021 at 10:27:50AM -0600, Alex G. wrote:
On 1/7/21 6:35 AM, Simon Glass wrote:
Hi Alexandru,
Hi Simon,
(pun alert!) A lot of your comments have to do with comments. I use comments
as a tool to add something of value to code. When the code is
self-documenting, comments don't help much.
See kernel coding style chapter 8.
Comments for comments sake are bad. Comments so that we can also have
reasonable generated documentation are good. Function prototypes fall
in to that second category to me, with few exceptions (and that we have
lots of bad examples isn't a good reason). The function names may well
make it obvious what's going on but the comments allow for generated
documentation to include that when explaining the not so obvious parts.
Thanks!
The problem with generated documentation is that it's not very useful.
People add comments for the sake of comments to have something
generated. Most often you end up with a detailed description of all the
details, but almost never the big picture. Nowadays, I don't even waste
my time reading generated documentation.
I am getting ready to send the new series with the goodies requested by
Simon. I don't find the new comments to be useful, and I find some to
spread out the code such that it hurts readability. They will be there
because you and Simon asked nicely, although I think you're wrong.
Alex
