This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/sis-site.git
The following commit(s) were added to refs/heads/main by this push:
new 193deebe Document the policy applied in recent changes: - Under which
condition to suppress a compiler warning. - Use of some HTML tags according
their semantic.
193deebe is described below
commit 193deebe7ff7ae09522b9fc6495074e85f312f4b
Author: Martin Desruisseaux <[email protected]>
AuthorDate: Mon Feb 12 18:51:24 2024 +0100
Document the policy applied in recent changes:
- Under which condition to suppress a compiler warning.
- Use of some HTML tags according their semantic.
---
content/code-patterns.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 44 insertions(+)
diff --git a/content/code-patterns.md b/content/code-patterns.md
index 6eb0abe5..df6d7676 100644
--- a/content/code-patterns.md
+++ b/content/code-patterns.md
@@ -6,6 +6,9 @@ This page lists some recommended code pattern for developing or
using Apache {{%
{{< toc >}}
+
+
+
# Referencing {#referencing}
This section lists recommended code pattern when using the `sis-referencing`
module.
@@ -21,6 +24,9 @@ Instead of patching the coordinate values, try to make sure
that the _Source CRS
and the _Target CRS_ (the coordinate space where to perform the work) are
properly defined,
and let the referencing engine performs the conversion from the source to the
target {{% CRS %}}.
+
+
+
# Rasters and coverages {#coverage}
This section lists recommended code pattern when using the `sis-coverage`
module.
@@ -43,6 +49,8 @@ because some raster data may be shared by many tiles having
identical content.
Furthermore changes in pixel values may be lost if {@code
releaseWritableTile(…)} is not invoked.
+
+
# International {#international}
This section lists recommended code pattern for internationalization.
@@ -84,6 +92,9 @@ for (int i=0; i<string.length();) {
}
```
+
+
+
# Logging {#logging}
Apache {{% SIS %}} uses the `java.util.logging` framework.
@@ -101,3 +112,36 @@ since developers use them for configuring their logging
(verbosity, destination,
All logging at `Level.INFO` or above shall be targeted to users or
administrators, not to developers.
In particular `Level.SEVERE` shall be reserved for critical errors that
compromise the application stability —
it shall not be used for exceptions thrown while parsing user data (file or
database).
+
+
+
+
+# Compiler warnings {#warnings}
+
+When a local variable in a method has the same name as a field in the
enclosing class,
+some compilers emit a _"Local variable hides a field"_ warning.
+This warning can be disabled with a
`@SuppressWarnings("LocalVariableHidesMemberVariable")` annotation.
+However, by convention Apache SIS applies this annotation only when the local
variable should have the same value as the field.
+Otherwise, the warning should be resolved. When a code hides a field, it
should be a statement such as
+`final Foo foo = this.foo;` or `final Foo foo = getFoo();` and may exist for
the following reasons:
+
+* `this.foo` is non-final and we want to make sure that it is not modified by
accident in the method.
+* `this.foo` is a volatile field, therefor should be read only once and cached
in the method for performance.
+* `getFoo()` computes the value of `this.foo` lazily.
+
+
+
+
+# Javadoc {#javadoc}
+
+Javadoc comments are written in HTML, not Markdown, both for historical
reasons and because HTML allows richer semantic.
+For example, for formatting a text in italic, the Javadoc should choose the
most appropriate of the following tags:
+
+* `<em>` for emphasis. A screen reader may pronounce the words using verbal
stress.
+* `<var>` for a variable to show like a mathematical symbol.
+* `<dfn>` for introducing a word defined by the nearby sentences.
+* `<cite>` for the title of a document, in particular an OGC/ISO standard.
+ Apache SIS uses also this tag for the name of a geodetic object in the EPSG
geodetic database,
+ in which case the object definition is considered as a document.
+ This tag can also be used for section titles.
+* `<i>` for rendering in italic for any reason than the above reasons.
