Estilo de Código

Aviso

This documentation refers to an outdated SpongeAPI version and is no longer actively maintained. While the code examples still work for that API version, the policies, guidelines, and some links may have changed. Please refer to the latest version of the documentation for those.

Nós seguimos as diretrizes do Google Java Style <https://google.github.io/styleguide/javaguide.html> com algumas adições e alterações que são descritas abaixo.

Dica

Poderás utilizar os nossos estilos de código para Eclipse ou IntelliJ IDEA para o teu IDE formatar o código corretamente por ti. Vê Preparando-se para o desenvolvimento para mais informações.

• Finais de linha

  • Usa os finais de linha do Unix quando fizeres commit (\n)

    • Os utilizadores de Git no windows podem usar git config --global core.autocrlf true para deixar o Git converter-los automaticamente

• Comprimento da coluna

  • 80 para Javadocs

  • 150 para o código

  • Pode fazer wrap quando achar que ajuda na leitura

• Indentação

  • Use 4 espaços para indentar, não use 2

• Parágrafos em branco

  • Utilize uma linha em branco antes do primeiro membro de uma classe, interface, enum, etc. (ex: depois de “class Example {”) e depois do ultimo membro

• Cabeçalhos de ficheiros

  • Os cabeçalhos dos ficheiros têm de conter os cabeçalhos da licença para o projeto. Use a função “licenseFormat” Gradle para adicionar-los automaticamente.

• Imports

  • As Imports devem ser agrupadas pela seguinte ordem, e os grupos devem ser separados por uma linha em branco

    • Imports Estáticos

    • Todos os outros Imports

    • Imports do Java

    • Imports do Javax

  • Isto difere do estilo do Google na medida em que os imports não estão agrupados por packages de top-level, mas estão todas num só grupo.

• Exceções

  • Para exceções que devem ser ignoradas, nomeia a variável da exceção “ignored”

• Field accesses

  • Classificar todos os field accesses com this

• Javadocs

  • Não utilize “@author”

  • Inclui parágrafos adicionais dentro de “<p>” e “</p>”

  • Utilize letra maiúscula na primeira letra das descrições dentro de cada “at clause”, ex: @param name Player to affect e não utilize pontos finais

Convenções de Código

• Use Opcionais em vez de retornar null na API

• Os parâmetros dos métodos que aceitem “null” têm de ter a notação “@Nullable” (de javax.*), todos os métodos e parâmetros são “@Nonnull” por defeito.

• Utiliza as Google Preconditions <https://code.google.com/p/guava-libraries/wiki/PreconditionsExplained> para “null” e verificação de argumentos.

A essência

Esperamos que leia as Google’s Java Conventions, ainda que sejam documentos bastante extensos. Para um início rápido, tem aqui um exemplo de código formatado corretamente:

/*
 * This file is part of Sponge, licensed under the MIT License (MIT).
 *
 * Copyright (c) SpongePowered.org <https://www.spongepowered.org>
 * Copyright (c) contributors
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
package com.example.java;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.Random;
import java.util.Optional;

public class Example {

    private static final Logger log = LoggerFactory.getLogger(Example.class);
    private static final Random random = new Random();
    private final String id = "test";

    /**
     * Returns an identifier approximately half of the time.
     *
     * <p>A static instance of {@link Random} is used to calculate the
     * outcome with a 50% chance.</p>
     *
     * @return The ID, if available
     */
    public Optional<String> resolveId() {
        log.info("ID requested");

        if (random.nextBoolean()) {
            return Optional.of(this.id);
        } else {
            return Optional.empty();
        }
    }

    /**
     * Returns an identifier approximately half of the time.
     *
     * <p>A static instance of {@link Random} is used to calculate the
     * outcome with a 50% chance. If the outcome is to not return the ID,
     * the given fallback ID is returned.</p>
     *
     * @param fallback A fallback name to return
     * @return The ID half of the time, the given fallback the other half
     */
    public String resolveId(String fallback) {
        return resolveId().orElse(fallback);
    }

}