<div dir="ltr"><div dir="ltr">On Fri, Dec 30, 2022 at 10:48 AM Brian Goetz <<a href="mailto:brian.goetz@oracle.com">brian.goetz@oracle.com</a>> wrote:</div><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">



<div style="overflow-wrap: break-word;">One thing that makes me a little uncomfortable is that @SW usually is used to say “the compiler can’t prove this is safe, but I am asserting it is.”  But this is different; the compiler has discovered the class is unsafe, and @SW is saying “I
 know, I know, stop telling me.”  So I think there’s an additional documentation opportunity here where, for the classes we had to annotate with @SW, we include an additional @apiNote of the form “This class behaves badly, oops”, with a link to a common doc
 page explaining the problem.  (While we don’t have to do this necessarily immediately, the chance of it falling on the floor if we don’t are higher.). Basically, what you’ve identified is that there are a  number of classes in the JDK which fail to follow
 best practices with regard to self-use from constructors.  We can’t turn back the clock, but we can mark these as “don’t code like my brother”, so people see these patterns of coding and realize they are not to be emulated.
</div></blockquote><div><br></div><div>Good point.</div><div><br></div><div>I think it's also worth considering which scenarios require such documentation. We have drawn the "boundary lines" at the compilation unit boundary, but this means (for example) there are package-private classes that generate warnings. Because these classes will end up in a module, which requires special effort to crack open, the warnings only really apply to JDK developers working in that same package.<br></div><div><br></div><div>Might be worth restricting this to classes that a "normal" person could "normally" extend, for some suitable definitions of "normal" and "normally".<br></div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div style="overflow-wrap: break-word;"><div>I also see in the code that there are two separate categories, LeakingThisInConstructor and this-escape; what’s the difference?</div></div></blockquote><div><br></div><div>Great question. I was surprised to stumble across existing code with <span style="font-family:monospace"><a class="gmail_plusreply" id="plusReplyChip-5">@SuppressWarnings("LeakingThisInConstructor")</a></span> annotations.</div><div><br></div><div>From what I can tell, these are leftovers from about 10 years ago when some developers were using NetBeans, which had just such a warning. I don't think they are relevant any more but I didn't want to presume anything so I left them in there.</div><div><br></div><div>Thinking about them more, we should probably just replace them because otherwise they will just continue to confuse...<br></div><div><br></div><div>-Archie<br></div><div><br></div></div>-- <br><div dir="ltr" class="gmail_signature">Archie L. Cobbs<br></div></div>