Skip to content

Commit a2f70e6

Browse files
trasktrask
authored
Refine UPPER_CASE field guideline (#17217)
1 parent 0411349 commit a2f70e6

File tree

16 files changed

+91
-73
lines changed

16 files changed

+91
-73
lines changed

‎.github/agents/knowledge/general-rules.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ When a "Knowledge File" is listed, load it from `knowledge/` before reviewing th
1515
| --- | --- | --- | --- |
1616
| General | Logic, correctness, reliability, safety, copy/paste mistakes, incorrect comments | Always | — |
1717
| Style | Style guide | Always | — |
18+
| Style | Uppercase field names should reflect semantic constants, not simply `static final` | Always | — |
1819
| Naming | Getter naming (`get` / `is`) | Always | — |
1920
| Naming | Module/package naming | New or renamed modules/packages | `module-naming.md` |
2021
| Javaagent | Advice patterns | `@Advice` classes | `javaagent-advice-patterns.md` |

‎docs/contributing/style-guide.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,24 @@ Fields should be declared `final` where possible.
9292

9393
Method parameters and local variables should never be declared `final`.
9494

95+
### Uppercase field names
96+
97+
Use uppercase (`SCREAMING_SNAKE_CASE`) for constant-like fields whose value is treated as a stable
98+
identifier or immutable descriptor.
99+
100+
Examples that may remain uppercase include:
101+
102+
- literal strings, numbers, and booleans that behave like module constants
103+
- semantic keys and handles such as `AttributeKey`, `ContextKey`, `VirtualField`,
104+
`MethodHandle`, and `Pattern`
105+
- canonical singleton or sentinel fields named `INSTANCE`, `EMPTY`, or `NOOP`
106+
107+
Do not use uppercase solely because a field is `static final`.
108+
109+
Use lower camel case for runtime-created collaborator objects even when they are `static final`,
110+
for example loggers, instrumenters, helpers, sanitizers, mappers, caches, and similar service
111+
objects.
112+
95113
### `@Nullable` annotation usage
96114

97115
**Note: This section is aspirational and may not reflect the current codebase.**

‎instrumentation/apache-elasticjob-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/apacheelasticjob/v3_0/ElasticJobSingletons.java‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,9 @@ public final class ElasticJobSingletons {
2020
DeclarativeConfigUtil.getInstrumentationConfig(GlobalOpenTelemetry.get(), "apache_elasticjob")
2121
.getBoolean("experimental_span_attributes/development", false);
2222

23-
private static final Instrumenter<ElasticJobProcessRequest, Void> INSTRUMENTER =
23+
private static final Instrumenter<ElasticJobProcessRequest, Void> instrumenter =
2424
createInstrumenter();
25-
private static final ElasticJobHelper HELPER = ElasticJobHelper.create(INSTRUMENTER);
25+
private static final ElasticJobHelper helper = ElasticJobHelper.create(instrumenter);
2626

2727
private static Instrumenter<ElasticJobProcessRequest, Void> createInstrumenter() {
2828
ElasticJobCodeAttributesGetter codeAttributesGetter = new ElasticJobCodeAttributesGetter();
@@ -42,7 +42,7 @@ private static Instrumenter<ElasticJobProcessRequest, Void> createInstrumenter()
4242
}
4343

4444
public static ElasticJobHelper helper() {
45-
return HELPER;
45+
return helper;
4646
}
4747

4848
private ElasticJobSingletons() {}

‎instrumentation/jetty/jetty-12.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jetty/v12_0/Jetty12Singletons.java‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@
1414
public final class Jetty12Singletons {
1515
private static final String INSTRUMENTATION_NAME = "io.opentelemetry.jetty-12.0";
1616

17-
private static final Instrumenter<Request, Response> INSTRUMENTER;
17+
private static final Instrumenter<Request, Response> instrumenter;
1818

1919
static {
20-
INSTRUMENTER =
20+
instrumenter =
2121
JavaagentHttpServerInstrumenters.create(
2222
INSTRUMENTATION_NAME,
2323
new Jetty12HttpAttributesGetter(),
@@ -31,10 +31,10 @@ public final class Jetty12Singletons {
3131
.init(context)));
3232
}
3333

34-
private static final Jetty12Helper HELPER = new Jetty12Helper(INSTRUMENTER);
34+
private static final Jetty12Helper helper = new Jetty12Helper(instrumenter);
3535

3636
public static Jetty12Helper helper() {
37-
return HELPER;
37+
return helper;
3838
}
3939

4040
private Jetty12Singletons() {}

‎instrumentation/rabbitmq-2.7/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/rabbitmq/RabbitInstrumenterHelper.java‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,10 @@ public class RabbitInstrumenterHelper {
2525
DeclarativeConfigUtil.getInstrumentationConfig(GlobalOpenTelemetry.get(), "rabbitmq")
2626
.getBoolean("experimental_span_attributes/development", false);
2727

28-
private static final RabbitInstrumenterHelper INSTRUMENTER_HELPER =
29-
new RabbitInstrumenterHelper();
28+
private static final RabbitInstrumenterHelper instrumenterHelper = new RabbitInstrumenterHelper();
3029

3130
public static RabbitInstrumenterHelper helper() {
32-
return INSTRUMENTER_HELPER;
31+
return instrumenterHelper;
3332
}
3433

3534
public void onPublish(Span span, String exchange, String routingKey) {

‎instrumentation/servlet/servlet-2.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/servlet/v2_2/Servlet2Singletons.java‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@ public final class Servlet2Singletons {
2323
public static final VirtualField<ServletResponse, Integer> RESPONSE_STATUS =
2424
VirtualField.find(ServletResponse.class, Integer.class);
2525

26-
private static final Servlet2Helper HELPER;
27-
private static final Instrumenter<ClassAndMethod, Void> RESPONSE_INSTRUMENTER;
26+
private static final Servlet2Helper helper;
27+
private static final Instrumenter<ClassAndMethod, Void> responseInstrumenter;
2828

2929
static {
3030
Servlet2HttpAttributesGetter httpAttributesGetter =
@@ -42,16 +42,16 @@ public final class Servlet2Singletons {
4242
spanNameExtractor,
4343
httpAttributesGetter);
4444

45-
HELPER = new Servlet2Helper(instrumenter);
46-
RESPONSE_INSTRUMENTER = ResponseInstrumenterFactory.createInstrumenter(INSTRUMENTATION_NAME);
45+
helper = new Servlet2Helper(instrumenter);
46+
responseInstrumenter = ResponseInstrumenterFactory.createInstrumenter(INSTRUMENTATION_NAME);
4747
}
4848

4949
public static Servlet2Helper helper() {
50-
return HELPER;
50+
return helper;
5151
}
5252

5353
public static Instrumenter<ClassAndMethod, Void> responseInstrumenter() {
54-
return RESPONSE_INSTRUMENTER;
54+
return responseInstrumenter;
5555
}
5656

5757
private Servlet2Singletons() {}

‎instrumentation/servlet/servlet-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/servlet/v3_0/Servlet3Singletons.java‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,30 +28,30 @@ public final class Servlet3Singletons {
2828

2929
private static final Instrumenter<
3030
ServletRequestContext<HttpServletRequest>, ServletResponseContext<HttpServletResponse>>
31-
INSTRUMENTER =
31+
instrumenter =
3232
AgentServletInstrumenterBuilder.<HttpServletRequest, HttpServletResponse>create()
3333
.build(INSTRUMENTATION_NAME, Servlet3Accessor.INSTANCE);
3434

35-
private static final ServletHelper<HttpServletRequest, HttpServletResponse> HELPER =
36-
new ServletHelper<>(INSTRUMENTER, Servlet3Accessor.INSTANCE);
35+
private static final ServletHelper<HttpServletRequest, HttpServletResponse> helper =
36+
new ServletHelper<>(instrumenter, Servlet3Accessor.INSTANCE);
3737

3838
public static final VirtualField<Servlet, MappingResolver.Factory> SERVLET_MAPPING_RESOLVER =
3939
VirtualField.find(Servlet.class, MappingResolver.Factory.class);
4040
public static final VirtualField<Filter, MappingResolver.Factory> FILTER_MAPPING_RESOLVER =
4141
VirtualField.find(Filter.class, MappingResolver.Factory.class);
4242

43-
private static final Instrumenter<ClassAndMethod, Void> RESPONSE_INSTRUMENTER =
43+
private static final Instrumenter<ClassAndMethod, Void> responseInstrumenter =
4444
ResponseInstrumenterFactory.createInstrumenter(INSTRUMENTATION_NAME);
4545

46-
private static final OutputStreamSnippetInjectionHelper SNIPPET_INJECTION_HELPER =
46+
private static final OutputStreamSnippetInjectionHelper snippetInjectionHelper =
4747
new OutputStreamSnippetInjectionHelper(() -> ExperimentalSnippetHolder.getSnippet());
4848

4949
public static ServletHelper<HttpServletRequest, HttpServletResponse> helper() {
50-
return HELPER;
50+
return helper;
5151
}
5252

5353
public static Instrumenter<ClassAndMethod, Void> responseInstrumenter() {
54-
return RESPONSE_INSTRUMENTER;
54+
return responseInstrumenter;
5555
}
5656

5757
@Nullable
@@ -64,7 +64,7 @@ public static MappingResolver getMappingResolver(Object servletOrFilter) {
6464
}
6565

6666
public static OutputStreamSnippetInjectionHelper getSnippetInjectionHelper() {
67-
return SNIPPET_INJECTION_HELPER;
67+
return snippetInjectionHelper;
6868
}
6969

7070
@Nullable

‎instrumentation/servlet/servlet-5.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/servlet/v5_0/Servlet5Singletons.java‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -29,33 +29,33 @@ public final class Servlet5Singletons {
2929

3030
private static final Instrumenter<
3131
ServletRequestContext<HttpServletRequest>, ServletResponseContext<HttpServletResponse>>
32-
INSTRUMENTER =
32+
instrumenter =
3333
AgentServletInstrumenterBuilder.<HttpServletRequest, HttpServletResponse>create()
3434
.build(INSTRUMENTATION_NAME, Servlet5Accessor.INSTANCE);
3535

36-
private static final ServletHelper<HttpServletRequest, HttpServletResponse> HELPER =
37-
new ServletHelper<>(INSTRUMENTER, Servlet5Accessor.INSTANCE);
36+
private static final ServletHelper<HttpServletRequest, HttpServletResponse> helper =
37+
new ServletHelper<>(instrumenter, Servlet5Accessor.INSTANCE);
3838

3939
public static final VirtualField<Servlet, MappingResolver.Factory> SERVLET_MAPPING_RESOLVER =
4040
VirtualField.find(Servlet.class, MappingResolver.Factory.class);
4141
public static final VirtualField<Filter, MappingResolver.Factory> FILTER_MAPPING_RESOLVER =
4242
VirtualField.find(Filter.class, MappingResolver.Factory.class);
4343

44-
private static final Instrumenter<ClassAndMethod, Void> RESPONSE_INSTRUMENTER =
44+
private static final Instrumenter<ClassAndMethod, Void> responseInstrumenter =
4545
ResponseInstrumenterFactory.createInstrumenter(INSTRUMENTATION_NAME);
46-
private static final OutputStreamSnippetInjectionHelper SNIPPET_INJECTION_HELPER =
46+
private static final OutputStreamSnippetInjectionHelper snippetInjectionHelper =
4747
new OutputStreamSnippetInjectionHelper(() -> ExperimentalSnippetHolder.getSnippet());
4848

4949
public static ServletHelper<HttpServletRequest, HttpServletResponse> helper() {
50-
return HELPER;
50+
return helper;
5151
}
5252

5353
public static Instrumenter<ClassAndMethod, Void> responseInstrumenter() {
54-
return RESPONSE_INSTRUMENTER;
54+
return responseInstrumenter;
5555
}
5656

5757
public static OutputStreamSnippetInjectionHelper getSnippetInjectionHelper() {
58-
return SNIPPET_INJECTION_HELPER;
58+
return snippetInjectionHelper;
5959
}
6060

6161
@Nullable

‎instrumentation/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/EmbeddedConfigFile.java‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,19 +28,19 @@ class EmbeddedConfigFile {
2828
// the entire configuration is copied from
2929
// https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/fileconfig/DeclarativeConfiguration.java#L66-L79
3030
// which is not public
31-
private static final ObjectMapper MAPPER;
31+
private static final ObjectMapper mapper;
3232

3333
static {
34-
MAPPER =
34+
mapper =
3535
new ObjectMapper()
3636
// Create empty object instances for keys which are present but have null values
3737
.setDefaultSetterInfo(JsonSetter.Value.forValueNulls(Nulls.AS_EMPTY));
3838
// Boxed primitives which are present but have null values should be set to null, rather than
3939
// empty instances
40-
MAPPER.configOverride(String.class).setSetterInfo(JsonSetter.Value.forValueNulls(Nulls.SET));
41-
MAPPER.configOverride(Integer.class).setSetterInfo(JsonSetter.Value.forValueNulls(Nulls.SET));
42-
MAPPER.configOverride(Double.class).setSetterInfo(JsonSetter.Value.forValueNulls(Nulls.SET));
43-
MAPPER.configOverride(Boolean.class).setSetterInfo(JsonSetter.Value.forValueNulls(Nulls.SET));
40+
mapper.configOverride(String.class).setSetterInfo(JsonSetter.Value.forValueNulls(Nulls.SET));
41+
mapper.configOverride(Integer.class).setSetterInfo(JsonSetter.Value.forValueNulls(Nulls.SET));
42+
mapper.configOverride(Double.class).setSetterInfo(JsonSetter.Value.forValueNulls(Nulls.SET));
43+
mapper.configOverride(Boolean.class).setSetterInfo(JsonSetter.Value.forValueNulls(Nulls.SET));
4444
}
4545

4646
private EmbeddedConfigFile() {}
@@ -99,11 +99,11 @@ static OpenTelemetryConfigurationModel convertToOpenTelemetryConfigurationModel(
9999
Map<String, String> flatProps) {
100100
Map<String, Object> nested = convertFlatPropsToNested(flatProps);
101101

102-
return MAPPER.convertValue(nested, OpenTelemetryConfigurationModel.class);
102+
return mapper.convertValue(nested, OpenTelemetryConfigurationModel.class);
103103
}
104104

105105
static ObjectMapper getObjectMapper() {
106-
return MAPPER;
106+
return mapper;
107107
}
108108

109109
/**

‎instrumentation/undertow-1.4/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/undertow/UndertowSingletons.java‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,13 @@
1616
public final class UndertowSingletons {
1717
private static final String INSTRUMENTATION_NAME = "io.opentelemetry.undertow-1.4";
1818

19-
private static final Instrumenter<HttpServerExchange, HttpServerExchange> INSTRUMENTER;
19+
private static final Instrumenter<HttpServerExchange, HttpServerExchange> instrumenter;
2020

2121
public static final VirtualField<Runnable, PropagatedContext> PROPAGATED_CONTEXT =
2222
VirtualField.find(Runnable.class, PropagatedContext.class);
2323

2424
static {
25-
INSTRUMENTER =
25+
instrumenter =
2626
JavaagentHttpServerInstrumenters.create(
2727
INSTRUMENTATION_NAME,
2828
new UndertowHttpAttributesGetter(),
@@ -41,10 +41,10 @@ public final class UndertowSingletons {
4141
}));
4242
}
4343

44-
private static final UndertowHelper HELPER = new UndertowHelper(INSTRUMENTER);
44+
private static final UndertowHelper helper = new UndertowHelper(instrumenter);
4545

4646
public static UndertowHelper helper() {
47-
return HELPER;
47+
return helper;
4848
}
4949

5050
private UndertowSingletons() {}

0 commit comments

Comments
 (0)