Sugestões e Melhores Práticas de Estilo

Os desenvolvedores que passaram algum tempo em grandes projetos entendem a importância dos comentários de código. Quando você está criando muitos recursos no mesmo aplicativo, as coisas tendem a ficar complicadas. Existem tantos bits de dados incluindo funções, referências de variáveis, valores de retorno, parâmetros… como você deve manter?

Não é surpresa que comentar seu código seja essencial, tanto em projetos solo quanto em equipe. Mas muitos desenvolvedores não sabem como proceder nesse processo. Eu descrevi alguns dos meus truques pessoais para criando comentários de código formatados e organizados. Padrões e modelos de comentários irão variar entre os desenvolvedores - mas no final você deve se esforçar comentários limpos e legíveis para explicar ainda mais áreas confusas em seu código.

Devemos começar a discutir algumas das diferenças na formatação de comentários. Isto lhe dará uma idéia melhor de quão detalhado você pode se tornar com o código do projeto. Depois, oferecerei algumas dicas e exemplos específicos que você pode começar a usar imediatamente!

Estilos de Comentário: Uma Visão Geral

Deve-se notar que essas idéias apresentadas são meramente diretrizes para comentários mais limpos. As linguagens de programação individuais não estabelecem diretrizes ou especificações sobre como configurar sua documentação.

Dito isto, os desenvolvedores modernos se agruparam para formatar seu próprio sistema de comentários de código. Eu vou oferecer alguns estilos mainstream e entrar em detalhes de sua finalidade.

Comentários em linha

Praticamente todas as linguagens de programação comentários inline. Estes são limitados ao conteúdo de uma linha e só comentam o texto depois de um certo ponto. Então, por exemplo, em C / C ++, você começa um comentário in-line como este:

// começa a listagem de variáveis ​​var myvar = 1;… 

Isso é perfeito para entrar no código por alguns segundos para explicar funcionalidade possivelmente confusa. Se você estiver trabalhando com vários parâmetros ou chamadas de função, poderá colocar vários comentários in-line nas proximidades. Mas o uso mais benéfico é um explicação simplista para pequena funcionalidade.

if (callAjax ($ params)) // executa com sucesso callAjax com parâmetros do usuário… code

Observe, acima de tudo, que o código precisaria estar em uma nova linha após o colchete de abertura. Caso contrário, tudo seria pego na mesma linha de comentário! Evite ir ao mar Como você geralmente não precisa ver comentários de linha única em toda a sua página, mas particularmente para junções confusas em seu código, elas são muito mais fáceis de serem descartadas no último minuto.

Blocos descritivos

Quando você precisa incluir uma grande explicação, geralmente, um único liner não faz o truque. Existem modelos de comentários pré-formatados usados ​​em quase todas as áreas de programação. Blocos descritivos são mais notavelmente vistos em torno de funções e arquivos de biblioteca. Sempre que você configura uma nova função, é uma boa prática adicionar um bloco descritivo acima da declaração.

/ ** * @desc abre uma janela modal para exibir uma mensagem * @param string $ msg - a mensagem a ser exibida * @return bool - sucesso ou falha * / function modalPopup ($ msg) … 

Acima é um exemplo simples de um comentário de função descritiva. Eu escrevi uma função presumivelmente em JavaScript chamado modalPopup que leva um único parâmetro. Nos comentários acima eu usei uma sintaxe similar ao phpDocumentor, onde cada linha é precedida por um @ símbolo seguido por uma tecla selecionada. Estes não vão afetar o seu código de forma alguma, então você pode escrever @descrição ao invés de @desc sem mudanças.

Essas pequenas chaves são chamadas tags de comentário que são documentados fortemente no site. Sinta-se livre para fazer o seu próprio e usá-los como quiser em todo o seu código. Eu acho que eles ajudam a manter tudo fluindo assim Eu posso verificar informações importantes de relance. Você também deve notar que eu usei o / * * / formato de comentário em estilo de bloco. Isso vai manter tudo muito mais limpo do que adicionar uma barra dupla começando em cada linha.

Comentários do grupo / turma

Além de comentar funções e loops, as áreas de bloqueio não são utilizadas com tanta freqüência. Onde você realmente precisa de forte bloquear comentários estão na cabeça de seus documentos de back-end ou arquivos de biblioteca. É fácil fazer todo o trabalho e escrever uma documentação sólida para cada arquivo em seu site - podemos ver essa prática em muitos CMS, como o WordPress..

A área superior da sua página deve conter comentários sobre o arquivo em si. Desta forma você pode verifique rapidamente onde você está editando ao trabalhar em várias páginas ao mesmo tempo. Além disso, você pode usar essa área como um banco de dados para as funções mais importantes que você precisará fora da aula.

/ ** * @desc esta classe manterá funções para interação com o usuário * exemplos incluem user_pass (), user_username (), user_age (), user_regdate () * @ autor Jake Rocheleau [email protected] * @required settings.php * / classe abstrata myWebClass  

Você pode ver que eu usei apenas uma pequena amostra de classe para o falso myWebClass código. Eu adicionei algumas informações meta com meu nome e endereço de e-mail para contato. Quando os desenvolvedores estão escrevendo código aberto, esta é geralmente uma boa prática para que outros possam contatá-lo para obter suporte. Esse também é um método sólido quando se trabalha em equipes de desenvolvimento maiores.

A etiqueta @requeridos Não é algo que eu já vi usado em outros lugares. Eu mantive o formato em alguns dos meus projetos, apenas em páginas onde eu customizava muitos métodos. Sempre que você incluir páginas em um arquivo, elas devem vir antes de você emitir qualquer código. Então, adicionar esses detalhes no bloco de comentários da classe principal é uma boa maneira de lembre quais arquivos são necessários.

Comentário de código front-end

Agora que abordamos 3 modelos de comentários importantes, vamos ver alguns outros exemplos. Existem muitos desenvolvedores front-end que mudaram do HTML estático para o código jQuery e CSS. Os comentários em HTML não são tão propositais quanto os aplicativos de programação, mas quando você está escrevendo bibliotecas de estilo e scripts de páginas, as coisas podem ficar confusas com o tempo.

JavaScript segue um método mais tradicional de comentar como o Java, PHP e C / C++. O CSS utiliza apenas os comentários no estilo de bloco delineados por uma barra e um asterisco. Você deve lembrar que os comentários serão exibidos abertamente para seus visitantes, já que nem CSS nem JS são analisados ​​no servidor, mas qualquer um desses métodos funciona muito bem para deixar informações informativas em seu código.

Especificamente, dividir arquivos CSS pode ser uma tarefa difícil. Estamos todos familiarizados com deixar um comentário in-line para explicar uma correção para o Internet Explorer ou Safari. Mas acredito que os comentários CSS possam ser usados ​​no nível jQuery e PHP os use. Vamos nos aprofundar na criação de grupos de estilos antes de tocar em algumas dicas detalhadas para comentários de código.

Grupos de estilos CSS

Para aqueles que vêm projetando CSS há anos, é quase uma segunda natureza. Você lentamente memoriza todas as propriedades, sintaxe e constrói seu próprio sistema para folhas de estilo. Através do meu próprio trabalho eu criei o que eu chamo agrupamento para emparelhar blocos CSS semelhantes em uma área.

Ao voltar para editar CSS, posso encontrar facilmente o que preciso em alguns segundos. A maneira que você escolhe para agrupar estilos depende inteiramente de você, e essa é a beleza desse sistema. Eu tenho alguns padrões pré-definidos que descrevi abaixo:

• @resets - tirando as margens do navegador padrão, preenchimento, fontes, cores, etc.
• @fonts - parágrafos, cabeçalhos, blockquotes, links, código
• @navigation - os principais links de navegação do site principal
• @layout - wrapper, contêiner, barras laterais
• @header & @footer - estes podem variar com base no seu design. Os estilos possíveis incluem links e listas não ordenadas, colunas de rodapé, títulos, sub-naves

Ao agrupar folhas de estilo, encontrei o sistema de marcação pode ajudar muito. No entanto, ao contrário do PHP ou JavaScript eu uso um único @grupo tag seguida por uma categoria ou palavras-chave. Eu incluí dois exemplos abaixo para que você possa ter uma ideia do que quero dizer.

/ ** @group footer * / #footer styles…

/ ** @ rodapé de grupo, fontes pequenas, colunas, links externos ** / 

Você poderia alternativamente adicionar um pouco de detalhes extras em cada bloco de comentário. Eu escolho mantenha as coisas simples e diretas Assim, as folhas de estilo são fáceis de percorrer. Comentar é tudo sobre documentação, contanto que você entenda a escrita, é bom ir!

4 dicas para melhorar o estilo de comentário

Passamos a primeira metade deste artigo examinando os vários formatos de comentários de código. Vamos agora discutir algumas dicas gerais para manter seu código limpo, organizado e fácil de entender.

1. Mantenha tudo legível

Às vezes, como desenvolvedores, esquecemos disso estamos escrevendo comentários para humanos lerem. Todas as linguagens de programação que entendemos são construídas para máquinas, então pode ser tedioso converter em texto escrito simples. É importante notar que não estamos aqui para escrever um artigo de pesquisa de nível universitário, mas apenas deixando dicas!

function getTheMail () // código aqui irá construir código de execução de e-mail / * se nossa chamada de função customizada sendMyMail () retornar true find sendMyMail () em /libs/mailer.class.php nós verificamos se o usuário preenche todos os campos e a mensagem é enviada! * / if (sendMyMail ()) return verdadeiro; // mantém a verdade e exibe o sucesso na tela

Mesmo apenas algumas palavras são melhor que nada. Quando você volta a editar e trabalhar em projetos no futuro, é surpreendente o quanto você vai esquecer. Como você não está olhando para as mesmas variáveis ​​e nomes de função todos os dias, você tende a esquecer lentamente a maioria do seu código. Assim você pode nunca deixe muitos comentários! Mas você pode deixar muitos comentários ruins.

Como regra geral, reserve um tempo para pausar e refletir antes de escrever. Pergunte a si mesmo o que é mais confuso sobre o programa e Como você pode explicar melhor isso em “manequim” língua? Considere também porque você está escrevendo o código exatamente como você é.

Alguns dos erros mais confusos surgem quando você esquece a finalidade das funções personalizadas (ou de terceiros). Deixe um comentário que leve a alguns outros arquivos se isso ajudar você a lembrar da funcionalidade mais fácil.

2. aliviar algum espaço!

Eu não posso enfatizar o quão importante é espaço em branco pode ser. Isso vai duplamente verdade para desenvolvedores PHP e Ruby que estão trabalhando em sites massivos com centenas de arquivos. Você estará olhando para este código durante todo o dia! Não seria ótimo se você pudesse simplesmente percorrer as áreas importantes?

$ dir1 = "/ home /"; // define o diretório inicial principal $ myCurrentDir = getCurDirr (); // define o diretório atual do usuário $ userVar = $ get_username (); // nome de usuário do usuário atual

No exemplo acima, você notará o preenchimento extra que coloquei entre comentários e código em cada linha. Como você está percorrendo os arquivos, esse estilo de comentário claramente se destacam. isto faz encontrar erros e corrigir seu código centenas de vezes mais fácil quando blocos variáveis ​​são tão limpar \ limpo.

Você poderia executar uma tarefa semelhante no código dentro de uma função onde você está confuso sobre como isso funciona, mas esse método acabaria por confundir seu código com comentários embutidos, e esse é exatamente o oposto do ordenado! Eu recomendo neste cenário adicionando um grande comentário de linha de bloco em torno da área da lógica.

$ (document) .ready (function () $ ('. sub'). hide (); // oculta a sub-navegação no pageload / ** verifica um evento de clique em uma âncora dentro .itm div previne o link padrão ação para que a página não mude em clique em acessar o elemento pai de .itm seguido pela próxima lista .sub para alternar abrir / fechar ** / $ ('. itm a'). live ('clique', função (e ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('fast');););

Este é um pequeno código do jQuery que visa uma navegação deslizante do submenu. O primeiro comentário é inline para explicar por que estamos escondendo todo o .sub classes. Acima do manipulador de eventos de clique ao vivo, usei um comentário de bloco e recuou toda a escrita para o mesmo ponto. Isso torna as coisas mais bonitas do que os parágrafos - especialmente para os outros que leem seus comentários..

3. Comentário ao codificar

Juntamente com o espaçamento adequado, este pode ser um dos melhores hábitos para entrar. Ninguém quer voltar ao programa depois de trabalhar e documentar cada peça. A maioria de nós nem sequer quer voltar e documentar as áreas confusas! Realmente é preciso muito trabalho.

Mas se você puder escrever os comentários enquanto estiver codificando tudo ainda estará fresco em sua mente. Normalmente, os desenvolvedores ficam presos em um problema e vasculham a web para obter a solução mais fácil. Quando você atinge o momento Eureka e resolve esse problema, geralmente há um momento de clareza onde você entende seus erros anteriores. Este seria o melhor tempo deixar comentários abertos e honestos sobre o seu código.

Além disso, você terá a prática de se acostumar a comentar todos os seus arquivos. A quantidade de tempo necessária para voltar e descobrir como algo funciona é muito maior depois que você já criou a função. Tanto o seu eu futuro quanto seus colegas de equipe agradecerão por deixar os comentários antes do tempo.

4. Lidando com erros de buggy

Não podemos ficar sentados em frente ao computador por horas escrevendo código. Acho que podemos tentar, mas em algum momento precisamos dormir! Você provavelmente terá que se separar do seu código para o dia com alguns recursos ainda quebrados. Neste cenário, é crucial que você deixar comentários longos e detalhados sobre onde você deixou as coisas.

Mesmo depois de uma noite fresca de sono, você pode se surpreender com o quão difícil pode ser voltar ao ritmo da codificação. Por exemplo, se você está criando uma página de upload de imagem e precisa deixá-la incompleta, deve comentar sobre onde no processo você parou. As imagens estão sendo carregadas e armazenadas na memória temporária? Ou talvez eles nem sejam reconhecidos no formulário de upload, ou talvez eles não sejam exibidos corretamente na página após o upload.

Comentar erros é importante por duas razões principais. Primeiro você pode facilmente pegar de onde você parou e tente novamente em mente para corrigir o (s) problema (s). E em segundo lugar você pode diferenciar entre a versão de produção ao vivo do seu site e os campos de teste. Lembre-se que os comentários devem ser usados ​​para explique por que você está fazendo algo, não exatamente o que faz.

Conclusão

O desenvolvimento de aplicativos e softwares da Web é uma prática satisfatória, embora difícil. Se você é um dos poucos desenvolvedores que realmente entende de software de construção, é importante amadurecer com suas habilidades de codificação. Deixar comentários descritivos é apenas uma boa prática a longo prazo, e você provavelmente nunca vai se arrepender!

Se você tiver sugestões de comentários de código mais claros, avise-nos na área de discussão abaixo!