change style for java files from comment to javadoc about addlicense

[willnorris]

Adding some notes from my quick research. Google's Java style guide does not instruct the style of comments to use for copyright and license information, only that it comes at the beginning of the file: https://google.github.io/styleguide/javaguide.html#s3-source-file-structure

I randomly spot-checked a half dozen Google Java projects and found:

• closure-compiler uses /* (example)
• error-prone uses /* (example)
• j2cl uses /* (example)
• nomulus uses // (example)
• flogger uses /* (example)
• guava uses /* (example)

I didn't bother checking to see if projects were internally consistent with which style they used. I just checked the first java file I could find.

I also dug into the public GitHub repo dataset in BigQuery, and ran some analysis on the sample_contents table there:

Java files that contain // copyright (accounting for spaces):

SELECT count(*) FROM `bigquery-public-data.github_repos.sample_contents` 
  WHERE 
    ENDS_WITH(sample_path, ".java")
    AND REGEXP_CONTAINS(content, r'(?im)^\s*//\s*copyright')

Count: 12091

Java files that contain /* copyright, /** copyright or * copyright (accounting for spaces):=

SELECT count(*) FROM `bigquery-public-data.github_repos.sample_contents` 
  WHERE 
    ENDS_WITH(sample_path, ".java")
    AND REGEXP_CONTAINS(content, r'(?im)^\s*/?\*+\s*copyright')

Count 119028

So block style comments /* */ seem to be used for copyright statements in java files more often than per-line comments // by a factor of about 10 to 1.

Given that, I'm inclined to make this change. @mco-gh, any objection?

[willnorris]

And since Kotlin was specifically mentioned in #65... block-style comments are also more common, but there is not actually enough data to draw any real conclusion (226 instances versus 7). I suspect that's because this sample_contents table was created in 2016, before Kotlin was as popular as it is today. We'd need to query the full contents table, which is still being updated today, to get meaningful data.

[willnorris]

I guess Scala is the other big JVM language, and one that's particularly relevant for us at Twitter.

For what it's worth, our add_license_headers.py script uses javadoc style /** */ for Scala and Kotlin, but per-line style // for Java. 🤷🏻

[mco-gh]

No objections from me for switching Java to /* style. Thanks for the research Will!

…

On Tue, 10 Aug 2021 at 00:13, Will Norris ***@***.***> wrote: I guess Scala is the other big JVM language, and one that's particularly relevant for us at Twitter. For what it's worth, our add_license_headers.py <https://github.com/twitter/repo-scaffolding/blob/master/add_license_headers.py> script uses javadoc style /** */ for Scala and Kotlin, but per-line style // for Java. 🤷🏻 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#46 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFAXF5WDK2UITFLCRX3YSLT4BOJTANCNFSM4PQFZV7A> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email> .

-- Marc Cohen Web: mco.dev Email: ***@***.*** Working with me: mco.dev/working-with-marc Feedback: How am I doing? Provide anonymous feedback! <https://www.increment.me/feedback/049628fd-7339-406d-9203-17d3ec8976bd/submit> Q: Why is this email three sentences or less? A: three.sentenc.es