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. : ```c /* Position of the reader */ unsigned int page; unsigned int character; unsigned int frame_counter; ``` versus ```c /* 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.: ```c /* 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: ```c /* 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
/* 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. -- https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/38#note_14037