Dev, o que são boas práticas?

Olá! Meu nome é Amanda Pereira.

Identação? Comentários? Documentação? Manual do usuário? O assunto de hoje é sobre boas práticas.
Afinal, qual são as práticas que irão facilitar o trabalho das pessoas que irão precisar fazer manutenção num código escrito por mim?

Depois de 7 meses de experiência, tenho a propriedade de falar que passei por situações complicadas que me levaram ao seguinte questionamento: como essa pessoa esperava que eu fosse entender esse código? Desde então, venho me dedicando pra que a próxima pessoa não passe por situações como essa, seguindo as seguintes práticas:

Comentários

Antes de ingressar no mercado de trabalho, achava que comentários se tornavam desnecessários se um código fosse legível, afinal,

$ nome = 'amanda'
return $nome;

é um trecho código auto-explicativo, certo?

Aí é que vem o erro de muitos: achar que comentários devem explicar linha por linha de um código, quando na verdade, devem explicar um código no geral;

/*
Esse relatório possui os dados X. Um dado, quando acontece algo Y, recebe status Z.

Status A: explicação do status.
Status B: explicação do status.
Status C: explicação do status.

Relação (nome da relação): O model X possui relação Many To Many com o model Y.
*/

Quem precisar dar manutenção na função que possui esse trecho de comentário, certamente não terá dificuldades para entender o que aquele código faz e as regras que ele possui.

Não repita código

Não repita uma função, crie uma genérica para ser reutilizada.

public function subtrairNumeros($num1, $num2){
  return $num1 - $num2;
}
public function somarNumeros($num1, $num2){
  return $num1 + $num2;
}

public function calculadora(){
  $num1 = 10; $num2 = 10;
  $soma = $this->somarNumeros($num1, $num2);
  $subtracao = $this->subtrairNumeros($num1, $num2);
}

Documentação

O que é essa tal de documentação? Como é feita?

De diversas maneiras. Uma documentação pode ser feita no README do seu repositório, num documento Word, através de comentários, através de UML. É essencial criar o diagrama do seu banco de dados e das relações que existem nele, assim, o próximo dev vai saber o nome de cada especificação e encontra-las vai ficar mais fácil.

Um arquivo md também é interessante.

Tenha sempre em mente formas de deixar claro a ideia do seu projeto, como utilizar e onde encontrar os recursos que você criou.

Código

Por fim, mantenha o seu código legível, se uma variável guarda uma idade, dê a ela o nome de $idade. Se a sua função soma números, dê a ela o nome somarNumeros(); Mantenha a identação adequada e não deixe seu código ultrapassar sua tela. Retorne mensagens de erro;

E o principal: se coloque no lugar do próximo profissional que ocupará seu lugar.