NagyDonat wrote: > To me the most interesting point it this comment of the PR summary: > > > I see that this block is a bit verbose (especially compared to the > > analogous comments in other checkers), but as this is one of the most > > complex checker families, I think it's useful to give this overview at the > > beginning of the source file. > > I'm all for comments like this. This is the right place to document the > design and the overall architecture. Potentially also including some > ascii-art if applicable. You probably know that IMO a comment inline in code > should be brief, preferably a single line or two, and under very exceptional > cases more.
@steakhal Thanks for clarifying this! I included that reasoning in the PR summary because after our last discussion about long comments (which were in the middle of the code and turned out to be mostly unnecessary – I was able to shorten them) I felt that you would perhaps oppose this other long comment as well. > The comment there would take up precious lines and make you scroll through. > In contrast to this a comment at the top of the file has plenty of space, and > a newcomer could (and should) opt in reading these. It seems that I have unusually high natural tolerance for comment blocks that take up lines and break the flow of the code, but I'll pay attention to this issue when I write comments. (To me, even a very large comment block is much less issue than a layer of indirection where I need to "Jump to definition" to see what happens behind that ambiguous function name.) https://github.com/llvm/llvm-project/pull/165443 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
