Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

change style for java files from comment to javadoc #46

Closed
Fetsivalen opened this issue Jul 31, 2020 · 4 comments · Fixed by #91
Closed

change style for java files from comment to javadoc #46

Fetsivalen opened this issue Jul 31, 2020 · 4 comments · Fixed by #91

Comments

@Fetsivalen
Copy link

Fetsivalen commented Jul 31, 2020

Hi,
From what I see for some reason license added to the .java files in comment style.
When addlicense tool supports the common style which is already applied to the ".c" files.

https://github.com/google/addlicense/blob/master/main.go#L216-L217
Would you accept the PR to change that style?

Example from Spring boot project (probably the most common case of the Java project)
https://github.com/spring-projects/spring-boot/blob/master/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/OnEndpointElementCondition.java#L1

@willnorris
Copy link
Collaborator

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:

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
Copy link
Collaborator

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
Copy link
Collaborator

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
Copy link
Contributor

mco-gh commented Aug 10, 2021 via email

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants