Coding style

Fluent interfaces

Introduction

See this wikipedia article for an explanation on fluent interfaces. Basically, it means that the getters are implemented slightly different than you may be used to. The usual getter method signature

public void setSomeThing(int someValue)

becomes

public EncapsulatingType setSomeThing(int someValue)

also, the final line in the method body becomes java return this;

You may change your IDE's getter generation code template. When applying method chaining, make sure to call the subclass' methods first, after that call the superclass methods. This is because the subclass method returns itself, allowing you to further chain the method. When a call returns a superclass instance, you won't be able to "get down" in the inheritance hierarchy. Example: PlacePort is a subclass of GameAction. PlacePort implements setTerritoryID, while GameAction implements setPlayer. So instead of

// bad, won't work
new PlacePort()
    .setPlayer(game.getPlayers().get(portCount % game.getPlayers().size())) // 
    .setTerritoryID(t.getID())  

you call the subclass' setTerritoryID first, like

// good, subclass' setter method called first
new PlacePort()
    .setTerritoryID(t.getID())  // territoryID belongs to PlacePort type
    .setPlayer(game.getPlayers().get(portCount % game.getPlayers().size())) // 

Why?

Most code from package soc.common is ported from SettleIn, which is written in C#. C# 3 has object initializers, which is a language implementation of fluent interfaces. It allows you to do:

server.Send(new ChatMessage()
{
    User = new User(),
    ChatMessage = "hello"
});

Java does not have this feature, and thus 'classical' fluent interfaces are used to increase code readability.