On Fri Nov 11 09:45:16 2022 +0000, Francisco Casas wrote:
## Regarding obvious comments I will remove the obvious comments in the next version, but I think it is not a waste of time to explain why I wrote them in the first place, maybe there can be some interesting discussion. I understand that some comments are obvious, but a potential reader may not know if the absence of a comment means that the field should indeed be understood in the most obvious way, or it is not obvious at all and just missing documentation. Another reason why I added obvious comments is that, sadly, comments are not associated to a portion of the code (like, say, comments in a Google Docs document review), but instead inserted on it. So, sometimes an obvious comment is useful to indicate that a previous comment that explains multiple lines doesn't explain the following one, e.g. :
/* Position of the reader */ unsigned int page; unsigned int character; unsigned int frame_counter;versus
/* Position of the reader */ unsigned int page; unsigned int character; /* Counter of frames currently displayed */ unsigned int frame_counter;In some personal projects I used to add comments with merely a `v` to indicate that the following line is self-explanatory, e.g.:
/* v */ unsigned int frame_counter;to address these problems, but I understand that that solution may be too unorthodox. Maybe empty comments are more acceptable, or at least adding empty lines to delimit the scope of the last comment:
/* Position of the reader */ unsigned int page; unsigned int character; unsigned int frame_counter;
Using empty lines to mark blocks of fields that are tied more strongly together is without doubt a good idea. As for obvious comments, I still have the feeling that something like ```c /* Reader position */ unsigned int reader_position; ``` it much more likely to distract rather then help a reader, but I agree that's a rather extreme case. I will trust your judgement on there to draw the line.