` (IDEA on Mac) or `F2` with Eclipse.
12. If you need to break the comment in to paragraphs for readability, use the HTML `` tag on an empty line. Do **not** use `
` or `` followed by `
`.
Example: Recommended JavaDoc
```java
/**
* Return a set view of the keys contained in this map for entries that
* satisfy the criteria expressed by the filter.
*
* Unlike the {@link #keySet()} method, the set returned by this method
* may not be backed by the map, so changes to the set may not reflected
* in the map, and vice-versa.
*
* @param filter the Filter object representing the criteria that
* the entries of this map should satisfy
*
* @return a set of keys for entries that satisfy the specified criteria
*/
public Set keySet(Filter filter);
```
13. It's unacceptable to leave auto-generated/default IDE comments in the code.
Example: Unacceptable JavaDoc
```java
/**
* Created by IntelliJ IDEA. User: flastname
*/
```
Example: Unacceptable JavaDoc
```java
// TODO Auto-generated method stub
```
14. Single line comments should have a space between the `//` and the first word.
Example: Recommended single line comment
```java
// this is a correct single line comment
```
Example: Unacceptable single line comment
```java
//This is an incorrect single line comment
```
General guidelines for single line/in-line comments:
14.a. Unlike JavaDoc comments, single line comments are not full sentences (no periods at the end of the comment); they are short phrases intended to guide the reader of the source
14.b. Avoid documenting the obvious
Example: Acceptable in-line comment
```java
// no need to synchronize; it is acceptable that two threads would
// instantiate a key set
Set set = m_setKeys;
if (set == null)
{
m_setKeys = set = instantiateKeySet();
}
```
Example: Unacceptable in-line comment
```java
// set flag to false
boolean fDone = false;
```
## 11. Formatting Casts
1. A space must be inserted after a cast.
Example: Acceptable cast
```java
String s = (String) obj;
```
Example: Unacceptable cast
```java
String s = (String)obj;
```
## 12. Use of Generics
1. It is only acceptable to generics if there is a clear benefit from their use to aid clarity, type-safety and usability of the resulting code.
2. It is **unacceptable** to use `` to suppress compile-time warnings. When using Generics you should always attempt to identify/narrow the required type. Generally it's only acceptable to use `` when dealing with reflection. For example, when using `Class` where it may not be possible to specify or narrow a type.
3. Like regular parameters, all generic parameters must be clearly documented in javadoc.
4. Like regular parameters, there should be a space between the generic parameters when they are declared. eg: `` not ``
5. Methods which take generified types as parameters should apply the PECS rule, namely they should take `Set` or `Set` rather then `Set`
6. Methods returning generified types should not use "? extends" or "? super" if at all possible.
## 13. Lambdas
1. Single-statement lambdas should be written on a single line:
```java
Consumer printer = s -> System.out.println(s);
```
2. Multi-statement lambdas should have a line break before an opening brace and the implementation should be indented 4 spaces:
```java
Consumer charPrinter = s ->
{
for (Character ch : s.toCharArray())
{
System.out.println(ch);
}
}
```
3. The parentheses should be used around lambda arguments only if required by the Java compiler (i.e. when there are two or more arguments).
4. The nesting of lambdas should be avoided, not only because it creates a [Pyramid of Doom](https://en.wikipedia.org/wiki/Pyramid_of_doom_(programming)), but more importantly because it makes inner lambdas non-remotable, thus breaking the support for remoting of outer lambdas as well.
Example: Don't do this
```java
Function encoder = s ->
{
StringBuilder sb = new StringBuilder();
BiFunction charEncoder = (ch, nPos) -> (char) (ch + nPos);
for (int i = 0; i < s.length(); i++)
{
sb.append(charEncoder.apply(s.charAt(i), i));
}
return sb.toString();
};
```
Instead, each inner lambda should be captured into a local variable that is accessible by the outer lambda.
Example: Do this instead
```java
BiFunction charEncoder = (ch, nPos) -> (char) (ch + nPos);
Function encoder = s ->
{
StringBuilder sb = new StringBuilder();
for (int i = 0; i < s.length(); i++)
{
sb.append(charEncoder.apply(s.charAt(i), i));
}
return sb.toString();
};
```
This way the `charEncoder` will become a captured argument of `encoder`, which will allow it to be properly remoted. It is important to note that method references are lambdas as well, which means that you should never use a method reference inside of another lambda directly either.
## 14. Streams
1. Simple uses of Stream API, where you call terminal operation immediately, can be written on a single line:
```java
InvocableMap.Entry oldestPerson = people.stream().max(Person::getAge);
```
2. However, if there are any intermediate operations in the pipeline, each intermediate operation and the terminal operation should be on its own line and indented 8 spaces:
```java
Map mapMinors = people.stream()
.map(entry -> entry.getValue())
.filter(person -> person.getAge() < 18)
.collect(toMap(Person::getId, Function.identity());
```
## 15. Use of @Override
The annotation is recommended when:
* Overriding a method from a super class, especially when said method fails to make a call to the method being overridden. e.g.: the method fails to call `super.method(...)`
* Anytime it may not be obvious that a method is overriding another method (i.e. a protected method)
The annotation is not recommended when:
* It is obvious that a method is being overridden (for example toString, equals, etc.)
* Implementing common interfaces (for example `Map.put`, `Map.get`, etc.)
* A class that is implementing a single interface
* Anonymous classes
## 16. Do not (directly) use Java's interruptible methods
This includes:
```java
Object.wait
Thread.sleep
Thread.interrupted
Selector.select
Lock.lockInterruptibly
Lock.tryLock(time)
Condition.await
LockSupport.park/parkNanos
```
Nope, not kidding, don’t use them instead use the com.oracle.coherence.common.base.Blocking static helpers correspond to each of them.
i.e. `o.wait()` becomes `Blocking.wait(o)`, `o.wait(1000)`, becomes `Blocking.wait(o, 1000)`, you get the idea.
Why? Well because now we can override any thread’s behavior while blocked in any of our code, specifically while in at an interruptible point. For an example of a feature which is dependent on this behavior see `com.oracle.coherence.common.base.Timeout`.
## 17. General Advice
This section provides general advice about coding style and implementation semantics. Where possible they should be followed as we've been burnt by failing to do so in the past.
1. If at all possible, avoid private methods. Use protected as they allow sub-classing/overriding. You never know when you'll need to sub-class an implementation
2. If a field has both a getter and setter, the field must be private.
3. If a field doesn't have a setter, it should be protected.
4. Fields should never be public.
5. Methods that access non-final members (field read or "getter" method calls) multiple times should pull the result into a local.
Example: Unacceptable - repeated read of `m_cElems` field.
```java
if (m_cElems > 0)
{
return m_cElems;
}
```
Example: Recommended - cache to a local
```java
int cElems = m_cElems;
if (cElems > 0)
{
return cElems;
}
```
# Tools
* IntelliJ settings file: [here](tools/conf/coh-idea-codescheme.xml)
* JIndent style: [here](tools/conf/coh-jindent-codingstyle.xjs)
# TDE
TDE is an entire development environment, IDE + ([bootstrapping](https://en.wikipedia.org/wiki/Bootstrapping_(compilers))) compiler, that allows the editing and compilation of components (.cdb files). If you source one of the [cfg* scripts](./bin) to set up your local shell session you can launch TDE by executing `tde` or there is an [osx package](tools/tde/bin/TDE.app) if you prefer. This is far from an introduction to TDE, however does provide some useful info for those that are trained in the art thereof.
## IDE Keyboard shortcuts
| Key stroke | Description |
|------------|-------------|
|Ctrl-A, Command-A|Select all.|
|Ctrl-B, Command-B|Go to a method declaration. works only within a scope of a single component.|
|Ctrl-C, Command-C|Copy text to the Clipboard.|
|Ctrl-X, Command-X|Cut text to the Clipboard.|
|Ctrl-V, Command-V|Paste text from the Clipboard.|
|Ctrl-Z, Command-Z|Undo the last change.|
|Ctrl-Y, Command-Y|Redo the last change.|
|Tab|Indent the current selection.|
|Shft-Tab|Outdent the current selection.|
|Ctrl-F, Command-F|Find text.|
|Ctrl-G, Command-G|Go to line.|
|Ctrl-F3, Command-F3|Use selection to find.|
|F3|Find next.|
|Shft-F3|Find previous.|
|F4|Find next error or search item or bookmark (depending on the Output panel tag).|
|Shft-F4|Find previous error or search item or bookmark (depending on the Output panel tag).|
|F5|Refresh the browser panel.|
|F7|Compile.|
|Ctrl-F2, Command-F2|Toggle the bookmark.|
|Ctrl-F4, Command-W|Close component.|
|Ctrl-Alt-Left, Command-Alt-Left|Go to the previous location within component (history).|
|Ctrl-Alt-Right, Command-Alt-Right|Go to the next location within component (history).|
|Ctrl-}, Command-}|Place the cursor on the matching brace.|
## Property values
* `[null]`
* `[instance]`
* `class-name`
* a line in the Doc of a property stating `@volatile` will make a property volatile (this allowed Gene to not enter GUI land)
## Custom font in the ScriptEditor
To use a custom font, before opening the TDE add any of the following properties to the $HOME/TDE.properties file:
```
UI.Font.Scripts.Size=12
UI.Font.Scripts.Name=Lucida Console
```
## Java debugger support
To allow Java debugging for TDE created code:
1. Add the following property to `$HOME/TDE.properties`:
```
Storage.Class.JavaLines=true
```
2. Recompile the TDE based code and build the Java source (listing)
```
cd $DEV_ROOT/prj
mvn install
```
> Note: uncompilable java sources based on the associated components, which can be used for debugging, are generated under `$DEV_ROOT/prj/coherence-core-components/target/artifact-sources`