I did some searching, but didn’t find the specific reference I was hoping to share about how to encourage good practices on a large code set…. Maybe someone else can chime in.
Basically, what you do is run additional checks on files that have been changed, so that as we modify a java file, if it’s missing the javadocs, then the precommit will fail. This way we don’t need to add boilerplate everywhere that never gets updated, which wouldn’t be helpful, but we also don’t need to add the docs everywhere before moving forward. JavaDocs are probably most valuable in files that actually are currently evolving and changing, so if we have some classes that never get touched, well, the value of adding JavaDocs to them would be the lowest presumably ;-). Over time, the classes that are evolving and getting the most use would gain more complete JavaDocs… > On Sep 28, 2023, at 3:33 PM, David Smiley <dsmi...@apache.org> wrote: > > When I see a class without any javadocs, especially a public top level > class, it's really sad and disappointing. My colleagues have noted the > same. I'd like to see a build mechanism to up our level of standards > here. Of course we have tons of existing such classes so a solution would > have to somehow accept our current reality. Or maybe we add /** > MISSING-JAVADOC */ everywhere? Has anyone yet looked into an approach? > > ~ David Smiley > Apache Lucene/Solr Search Developer > http://www.linkedin.com/in/davidwsmiley _______________________ Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw> This e-mail and all contents, including attachments, is considered to be Company Confidential unless explicitly stated otherwise, regardless of whether attachments are marked as such.
