From b817db6cf150af660130fcf9c7b69893ab5ee1a6 Mon Sep 17 00:00:00 2001 From: Joel Lappalainen Date: Tue, 8 Oct 2024 17:13:24 +0300 Subject: [PATCH 1/5] Update code style for ordering things inside classes --- doc/dev/decisionrecords/Codestyle.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/doc/dev/decisionrecords/Codestyle.md b/doc/dev/decisionrecords/Codestyle.md index f9ffc1a9056..1b3c73a886e 100644 --- a/doc/dev/decisionrecords/Codestyle.md +++ b/doc/dev/decisionrecords/Codestyle.md @@ -118,18 +118,15 @@ The provided formatter will group class members in this order: 1. `static` `final` fields 2. `static` fields 3. `static` initializer - 4. `final` fields - 5. fields - 6. class initializer (avoid using it) - 7. Constructor - 8. `static` methods - 9. `static` getter and setters - 10. methods - 11. getter and setters - 12. enums - 13. interfaces - 14. `static` classes - 15. classes + 4. other fields + 5. class initializer (avoid using it) + 6. Constructor + 7. methods + 8. getter and setters + 9. enums + 10. interfaces + 11. `static` classes + 12. classes 5. Each section of members are sorted by visibility: 1. ´public´ 2. package private From f2075c7530a103fc4a997b918f8f57bb05005923 Mon Sep 17 00:00:00 2001 From: Joel Lappalainen Date: Thu, 10 Oct 2024 17:06:09 +0300 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Thomas Gran --- doc/dev/decisionrecords/Codestyle.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/doc/dev/decisionrecords/Codestyle.md b/doc/dev/decisionrecords/Codestyle.md index 1b3c73a886e..e3278d0fd9e 100644 --- a/doc/dev/decisionrecords/Codestyle.md +++ b/doc/dev/decisionrecords/Codestyle.md @@ -115,18 +115,19 @@ The provided formatter will group class members in this order: 2. Overridden methods are kept together 3. Dependent methods are sorted in a breadth-first order. 4. Members are sorted like this: - 1. `static` `final` fields - 2. `static` fields - 3. `static` initializer - 4. other fields - 5. class initializer (avoid using it) - 6. Constructor - 7. methods - 8. getter and setters - 9. enums - 10. interfaces - 11. `static` classes - 12. classes + 1. `static` `final` fields (constants) + 2. `static` fields (avoid) + 3. instance fields + 4. static initializer + 5. class initializer + 6. constructor + 7. `static` factory methods + 8. methods + 9. getter and setters + 10. `private` enums (avoid `public`) + 11. interfaces + 12. `private static` classes (avoid `public`) + 13. instance classes (avoid) 5. Each section of members are sorted by visibility: 1. ´public´ 2. package private From ec01a7df0fff175602a8b68386ee8e40f7aeba15 Mon Sep 17 00:00:00 2001 From: Joel Lappalainen Date: Thu, 10 Oct 2024 17:24:27 +0300 Subject: [PATCH 3/5] Update doc/dev/decisionrecords/Codestyle.md Co-authored-by: Thomas Gran --- doc/dev/decisionrecords/Codestyle.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/dev/decisionrecords/Codestyle.md b/doc/dev/decisionrecords/Codestyle.md index e3278d0fd9e..e647581d6f3 100644 --- a/doc/dev/decisionrecords/Codestyle.md +++ b/doc/dev/decisionrecords/Codestyle.md @@ -122,8 +122,9 @@ The provided formatter will group class members in this order: 5. class initializer 6. constructor 7. `static` factory methods - 8. methods + 8. `public` methods 9. getter and setters + 8. `private`/package methods 10. `private` enums (avoid `public`) 11. interfaces 12. `private static` classes (avoid `public`) From 8704e9bf255958ce198593170d9bb3b4c91cd41c Mon Sep 17 00:00:00 2001 From: Joel Lappalainen Date: Thu, 10 Oct 2024 17:25:27 +0300 Subject: [PATCH 4/5] Remove separate visibility rules --- doc/dev/decisionrecords/Codestyle.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/dev/decisionrecords/Codestyle.md b/doc/dev/decisionrecords/Codestyle.md index e647581d6f3..722205a8b02 100644 --- a/doc/dev/decisionrecords/Codestyle.md +++ b/doc/dev/decisionrecords/Codestyle.md @@ -129,11 +129,6 @@ The provided formatter will group class members in this order: 11. interfaces 12. `private static` classes (avoid `public`) 13. instance classes (avoid) -5. Each section of members are sorted by visibility: - 1. ´public´ - 2. package private - 3. ´protected´ - 4. ´private´ ### JavaDoc Guidlines From 05a6f6dab90362af5cee1276be5e19fbc16adcae Mon Sep 17 00:00:00 2001 From: Joel Lappalainen Date: Thu, 10 Oct 2024 17:30:05 +0300 Subject: [PATCH 5/5] Put javadoc instructions in one place --- doc/dev/decisionrecords/Codestyle.md | 7 ++++++- doc/user/Developers-Guide.md | 10 ---------- 2 files changed, 6 insertions(+), 11 deletions(-) diff --git a/doc/dev/decisionrecords/Codestyle.md b/doc/dev/decisionrecords/Codestyle.md index 722205a8b02..146063bbeef 100644 --- a/doc/dev/decisionrecords/Codestyle.md +++ b/doc/dev/decisionrecords/Codestyle.md @@ -132,7 +132,12 @@ The provided formatter will group class members in this order: ### JavaDoc Guidlines -What to put in Javadoc: +As a matter of [policy](http://github.com/opentripplanner/OpenTripPlanner/issues/93), all new +methods, classes, and fields should include comments explaining what they are for and any other +pertinent information. For Java code, the comments should follow industry standards. It is best to +provide comments that not only explain *what* you did but also *why you did it* while providing some +context. Please avoid including trivial Javadoc or the empty Javadoc stubs added by IDEs, such as +`@param` annotations with no description. - On methods: - Side effects on instance state (is it a pure function) diff --git a/doc/user/Developers-Guide.md b/doc/user/Developers-Guide.md index 889cfb0d10b..f5633ff17b1 100644 --- a/doc/user/Developers-Guide.md +++ b/doc/user/Developers-Guide.md @@ -106,16 +106,6 @@ standards: 2. Strip out any unneeded information by using the `osmium filter-tags` as describe in [Preparing OSM](Preparing-OSM.md) -### Code Comments - -As a matter of [policy](http://github.com/opentripplanner/OpenTripPlanner/issues/93), all new -methods, classes, and fields should include comments explaining what they are for and any other -pertinent information. For Java code, the comments should use the -[JavaDoc conventions](http://java.sun.com/j2se/javadoc/writingdoccomments). It is best to provide -comments that not only explain *what* you did but also *why you did it* while providing some -context. Please avoid including trivial Javadoc or the empty Javadoc stubs added by IDEs, such as -`@param` annotations with no description. - ### Itinerary and API Snapshot Tests To test the itinerary generation, and the API there are snapshot test which save the result of the