On 1/7/21 11:29 AM, Simon Glass wrote:
Hi Alex,
On Thu, 7 Jan 2021 at 09:27, Alex G. mr.nuke.me@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