Este é um discurso retórico que todo desenvolvedor precisa ouvir ou compartilhar.
Hoje, fui inspirado a dizer o seguinte : Não consigo contar quantas vezes fui apresentado a um novo aplicativo e quase rasguei meu cabelo por causa de como ele estava mal encaixado. Quero dizer, pelo amor de Deus, alguns de vocês podem pelo menos fingir que outro ser humano vai ver o que você escreveu!
O que estou querendo dizer é: organizar, detalhar e documentar seu código.
É difícil?
Não . Isso leva mais tempo? Não com prática e consistência.
As pessoas vão gostar? Sim.
PASSO 1: Organize
A maioria dos desenvolvedores não tem problemas com este, mas a maioria possui algumas áreas que poderiam ser melhoradas. A primeira área de problema é o uso de espaços VS tabs. Resumindo, siga / crie o guia de estilo dos projetos. (veja o comentário de @Paprikkastudio abaixo)
Alguns mais comuns são sistemas de nomenclatura de arquivos e layout de arquivos. Se você carregar várias classes em PHP, separe cada classe em arquivos como thisThing.class.phpe thatThing.class.php; ou se você tiver um arquivo CSS extenso, considere adicionar um “índice” no início.
Pequenos extras como esses são extremamente úteis para outras pessoas que estão tentando navegar em seu código. Além disso, pode ser muito benéfico para você, se você precisar encontrar algo rapidamente.
A partir daqui, quase chega ao bom senso. Se seu código se parece com um quebra-cabeça de palavras cruzadas, considere revisá-lo. Se você tiver um bloco de comentário, tente não deixar uma linha exceder ~ 100 caracteres (para aqueles de nós não abençoados com o dom de ‘quebra de linha’). E assim por diante.
PASSO 2: Detalhe
É aqui que seus blocos / linhas de comentários são mais úteis. Sempre que o código ficar um pouco confuso, ou usar alguma coisa estranha nem mesmo mencionada em nenhum outro lugar do arquivo, adicione um comentário. Diga-nos o que diabos está acontecendo aqui.
Quando algo fica confuso, uma pequena dica pode ajudar. Inserir um rápido # thisVar is now = thatVarou algo parecido pode ajudar a esclarecer as coisas.
Quando se trata de coisas aleatórias que não são mencionadas com frequência … Embora eu adore passar 3 horas olhando arquivos e descobri que o $someVariablecriado por thisFunctioné booleano, não vou querer esfaqueá-lo com uma colher enferrujada se você apenas escrever o Segue:
// $thisVariable (bool) is created by thisFunction() in /this/path/here.php
Muitas pessoas preferem usar PHPDoc (ou sistemas semelhantes), como um substituto. Em geral, acho isso aceitável, mas dicas de código adicionais, conforme necessário, ainda são recomendadas.
PASSO 3: Documento
Embora eu possa continuar para sempre sobre isso , apenas documente seu código. Faça com que alguém possa ler e entender o que seu código basicamente faz. E enquanto você está nisso, use um sistema de controle de versão que faça sentido .
Seus usuários / desenvolvedores vão adorar você, você economizará tempo, ganhará mais dinheiro … Simplesmente faça.
Obrigado pela leitura
Se você gostou do que escrevi, considere aprovar este protocolo ou me endossar .
Se você quiser ver mais coisas minhas, pode ver outros protocolos que escrevi ou visitar meu perfil .