8000 Add new Sample Format guidelines. (#1406) · hrodriguezv/java-docs-samples@ee82760 · GitHub
[go: up one dir, main page]
Skip to content

Commit ee82760

Browse files
kurtisvgkurtisvg
authored
Add new Sample Format guidelines. (GoogleCloudPlatform#1406)
* Add SAMPLE_FORMAT.md. * Add best practices. * Update Contributing.md. * Better exception example.
1 parent 06fc90a commit ee82760

File tree

2 files changed

+133
-7
lines changed

2 files changed

+133
-7
lines changed

‎CONTRIBUTING.md

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,7 @@ accept your pull requests.
4040

4141
## Contributing a new sample
4242

43-
1. App Engine Standard samples all go into `/appengine` (java 7) or `/java8-appengine` (Java 8) (if you're contributing a group of samples,
44-
please put the App Engine Standard sample into `/appengine` and provide a link in both `README.md`'s for
45-
the project for the additional sample.
46-
47-
1. App Engine Flexible samples all go into `/flexible`
48-
49-
1. Technology samples go into the project root.
43+
1. See the [SAMPLE_FORMAT.md](SAMPLE_FORMAT.md) for guidelines on the preferred sample format.
5044

5145

5246
## Build Tools

‎SAMPLE_FORMAT.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Samples Format
2+
3+
This doc maintains an outline for 'snippet' samples specific to Java. Currently, the java canonical
4+
samples in this format are located
5+
[here](https://github.com/GoogleCloudPlatform/java-docs-samples/tree/master/dlp/src/main/java/dlp/snippets).
6+
7+
8+
## Specific Goals
9+
This sample format is intended to help enforce some specific goals in our samples. Even if not
10+
specifically mentioned in the format, samples should make best-effort attempts in the following:
11+
12+
* __Easily runnable__ - samples should be as easy for a user to run as possible. Users should be
13+
able to copy and paste the code into their own environments and run with as few and transparent
14+
modifications as possible.
15+
16+
* __Teach through code__ - samples should teach users how and why specific best practices should
17+
be implemented and performed when interacting with our services.
18+
19+
* __Idiomatic__ - examples should make best attempts to remain idiomatic and encourage good
20+
practices that are specific to a language or practice.
21+
22+
## Format Guidelines
23+
24+
### Project Location
25+
Samples should be in a project folder under the name of the product the snippet represents.
26+
Additional sub folders should be used to differentiate groups of samples. Folder and package paths
27+
should try to avoid containing unnecessary folders to allow users to more easily navigate to the
28+
snippets themselves.
29+
30+
### Project Dependencies
31+
Project should have a `pom.xml` that is readably formatted, declares a parent pom as shown below,
32+
and declares all dependencies needed for the project. Best attempts should be made to minimize
33+
necessary dependencies without sacrificing the idiomatic practices.
34+
35+
```xml
36+
<!--
37+
The parent pom defines common style checks and testing strategies for our samples.
38+
Removing or replacing it should not affect the execution of the samples in anyway.
39+
-->
40+
<parent>
41+
<groupId>com.google.cloud.samples</groupId>
42+
<artifactId>shared-configuration</artifactId>
43+
<version>SPECIFY_LATEST_VERSION</version>
44+
</parent>
45+
```
46+
47+
### Project Setup
48+
The README.md should contain instructions for the user to get the samples operable. Ideally, steps
49+
such as project or resource setup should be links to Cloud Documentation. This is to reduce
50+
duplicate instructions and README maintenance in the future.
51+
52+
### Sample Structure
53+
Each snippet should be be contained in its own file, within a class with a name descriptive of
54+
the snippet and a similarly named function. Region tags should start below the package, but should
55+
include the class and any imports in full. Additional functions can be used if it improves
56+
readability of the sample.
57+
58+
### Function Parameters
59+
Function parameters should be limited to what is absolutely required for testing. For example,
60+
project specific information (such as `projectId`) or a `filePath` for an external file are
61+
allowed. A parameter for the type of a file or a specific action is not.
62+
63+
Any declared function parameters should include a commented out example of how that parameter could
64+
be declared. This provides both an example of how to derive the variables and what information they
65+
should represent.
66+
67+
### Function Return Type
68+
The function in the snippet should not return any value. Instead, they should print the results of
69+
actions to the console to be validated later.
70+
71+
### Exception Handling
72+
The snippet should show how to correctly handle Exceptions that occur during the snippet. Top level
73+
exceptions can be handled by logging the exception to `System.out.println`. If the exception is
74+
something the user may commonly encounter, include a comment explaining how to avoid or handle
75+
correctly.
76+
77+
Example:
78+
```java
79+
try {
80+
// Do something
81+
} catch (IllegalArgumentException e) {
82+
// IllegalArgumentException's are thrown when an invalid argument has been passed to a function.
83+
// This error should be logged to that the root cause can be debugged and prevented in the future.
84+
System.out.println("Error during functionName: \n" + e.toString());
85+
}
86+
```
87+
88+
### Client Initialization
89+
The preferred style for initialization is to use a try-with-resources statement with a comment
90+
clarifying how to handle multiple requests and clean up instructions.
91+
92+
Example:
93+
```java
94+
// Initialize client that will be used to send requests. This client only needs to be created
95+
// once, and can be reused for multiple requests. After completing all of your requests, call
96+
// the "close" method on the client to safely clean up any remaining background resources.
97+
try (DlpServiceClient dlp = DlpServiceClient.create()) {
98+
// Do something
99+
} catch (Exception e) {
100+
System.out.println("Error during functionName: \n" + e.toString());
101+
}
102+
```
103+
104+
### Arrange, Act, Assert
105+
Samples should generally follow the following outline:
106+
* _Arrange_ - Create and configure the components for the request. Avoid nesting these components,
107+
as often they use Builders which can hinder readibility.
108+
* _Act_ - Send the request and receive the response.
109+
* _Assert_ - Verify the call was successful or that the response is correct. This is often done by
110+
print contents of the response to stdout.
111+
112+
### Testing
113+
Snippets should have tests that should verify the snippet works and compiles correctly. Creating
114+
mocks for these tests are optional. These tests should capture output created by the snippet to
115+
verify that it works correctly. See the tests in the cannoncial for an example of how to do this
116+
correctly.
117+
118+
### External Resources
119+
Use of environment variables over system properties is strongly preferred for configuration.
120+
121+
Any additional files required should be stored in `src/test/resources`.
122+
123+
## Additional Best Practices
124+
125+
The following are some general Java best practices that should be followed in samples to remain
126+
idiomatic.
127+
128+
### Time
129+
Use the `java.time` package when dealing with units of time in some manner.
130+
131+
### Logging
132+
Use `java.util.logging` for consistent logging in web applications.

0 commit comments

Comments
 (0)
0