Coding style

Overview

• Fluent interfaces
• ISomeInterface

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

    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.

Interfaces

When adding another interface, the ISomeInterface naming convention is used. This increases clarity when determining what type is used in code.