On 1/7/21 11:29 AM, Simon Glass wrote:
Hi Alex,
On Thu, 7 Jan 2021 at 09:27, Alex G. <mr.nuke...@gmail.com> 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.
What comments can do, is increase code size and break code flow -- there
is a cost to having them. I'm certain you've seen functions that need to
be scrolled up and down because of a huge comment smack in the middle.
I'll address individual comment comments below.
Don't get me started on comments in the kernel...there seems to almost
be a ban on them :-)
We used to follow the same approach but now we have comments for
non-trivial code. Comments and tests are closely related.
- if there is no comment, we don't know what the function is supposed
to do so we can't change it (there is no contract), we are not sure if
line 5 is a bug or a real quirk, casual readers can't understand what
is going on, the automated docs don't produce anything, no one wants
to refactor it, etc.
- if there is no test, presumably the code doesn't work now, if it ever did
I will add each of the comments you are requesting, but not for the
reasons quoted. The comments that I could write won't add anything of
value -- they would just make the code larger, and increase the
cognitive load. You are the maintainer, and starting an argument would
be pointless. In the end, comments don't get compiled, and the code
works just the same :)
[snip]
Again,
this is not Linux and people don't have as much time to cogitate on
code.
I resent that statement. It takes me longer to do a task in u-boot than
it would take me to do a similar task in linux. In the context of
comments (note I intentionally did not say 'documentation'), does
plastering the same information over and over in a way that hides the
essence really help? I think the current path is misguided, and will
only aggravate the problem. (I'll add the comments, though)
They are just trying to get their device working.
That's true for linux too.
[snip]
All other comments will be addressed in v3
