Void ou return? O que ninguém te explica sobre "devolver um valor" em Apex

Beleza, isso aqui é chato de admitir, mas quase todo mundo trava nesse ponto quando começa a programar, e ninguém explica direito. Você escreve um método, ele "faz a conta", mas na hora de usar o resultado lá fora, nada aparece. E aí bate a pergunta: "mas ele não calculou? Onde foi parar esse valor?"

Bora destrinchar isso.

O que significa "devolver um valor"

Quando você chama um método e guarda o resultado numa variável, tipo assim:

Decimal totalComImposto = calcularImposto(1000);

depois dessa linha, totalComImposto tem um número de verdade dentro dela, pronta pra ser usada no resto do código. O método calculou algo e entregou esse algo pra quem chamou. Isso é retornar.

Segundo a Apex Developer Guide, todo método precisa declarar um tipo de retorno, e esse tipo é exatamente o que ele promete devolver quando termina.

Void é outra conversa

Agora olha esse método:

public void registrarLog(String mensagem) {
    System.debug(mensagem);
}

Você chama ele assim:

registrarLog('Processo iniciado');

Repara: não tem nada do lado esquerdo recebendo valor. Não existe String resultado = registrarLog(...), porque não tem resultado nenhum pra guardar.

A documentação oficial é direta sobre isso: use void quando o método não devolve valor. Ele faz uma ação, nesse caso escreve no log, mas na sua mão, depois de chamar ele, não sobra nenhum dado novo.

"Mas ele fez alguma coisa, então ele devolveu, não?"

Essa é a pegadinha. Fazer uma ação e devolver um valor são duas coisas separadas.

Registrar um log é uma ação, tem efeito real, fica gravado ali, mas não gera um dado pra você usar depois no código. Já calcular um imposto é um cálculo que produz um resultado, e esse resultado precisa viajar de volta pra quem chamou, pra alguém poder mostrar na tela, salvar num campo, etc.

Só uso um System.debug lá dentro, não resolve?

Não. E essa é a parte que mais confunde.

public void calcularImposto(Decimal valorBase) {
    Decimal imposto = valorBase * 0.1;
    System.debug(imposto); // você vê o valor aqui, mas só aqui
}

Enquanto o código está rodando dentro do método, a variável imposto existe de verdade, com o valor calculado lá dentro. Só que, segundo o conceito de escopo de variável da própria linguagem, uma variável declarada dentro de um método só existe dentro daquele método. Quando o método termina, ela desaparece.

System.debug() só imprime o valor no log, pra você visualizar enquanto testa ou depura. Não transporta esse valor pra lugar nenhum do código. Quem chamou o método continua sem acesso a ele.

O return é o "transporte"

public Decimal calcularImposto(Decimal valorBase) {
    Decimal imposto = valorBase * 0.1;
    return imposto;
}

return é o mecanismo que pega o valor de dentro do método, onde ele existe só temporariamente, e leva pra fora, onde quem chamou pode guardar numa variável e continuar usando.

Sem return, o valor nasce e morre dentro do método. Ninguém do lado de fora nunca chega perto dele.

Resumindo

Fontes oficiais

• Salesforce Developers: Apex Class Methods