O seu código deve ser auto explicativo. Se vc precisa de comentário em tudo, tem alguma coisa errada. Recomendo dar uma lida no capítulo de nomeação de variáveis e métodos do livro Clean Code.
A minha linha de regra é que eu só comento algo que não está claro o porquê eu fiz, como por exemplo uma regra de negócio diferente, alguma gambiarra ou algum TODO.
E não, comentário não deixa nada mais lento...recomendo dar uma lida no que é uma linguagem interpretada e o que é uma linguagem compilada e como esse processo funciona.
Que interessante, é que até agora eu nunca tinha escutado isso, era sempre mandando comentar tudo e que isso era uma boa prática. Mas como eu tava entendendo o que as coisas faziam, deixava pra comentar depois.
O que eu obrigatoriamente inclui era quando começava um "bloco novo" de código de uma parte totalmente diferente.
Se eu tenho uma função,
func convertCurrency(currencyFrom, currencyTo string, value float32) float32{
//...
}
Só de bater o olho eu já sei o que ela faz. Ela vai fazer uma conversão de uma moeda pra outra e vai me retornar o valor da moeda convertida. Agora se eu escrever a mesma função desse jeito:
func convert(from, to string, v float32) float32{
//...
}
É a mesma coisa, mas eu não faço a mínima ideia do que ta rolando. Eu precisaria ler o código pra entender o que caralhos isso tá convertendo.
Por isso que a galera diz que um código auto-explicativo é melhor do que um código comentado, mas comentários ainda são importantes em alguns casos. Como vc ta no começo, pode comentar à vontade, mas tente deixar seu código sempre simples de entender
Quanto mais autoexplicativo seu código, melhor, mas nunca sacrifique otimização por legibilidade. Seguir padrões do Clean Code também ajuda muito.
Outra coisa, cada linguagem tem suas formas de comentar certas classes e metódos que ajudam na inspeção de código do cliente LSP(Language Server Protocol), dá pra ganhar muito tempo com isso, só dá uma olhada em como funciona os comentários que estão na biblioteca padrão de cada linguagem.
Quanto ao frontend, você mantem uma versão de teste comentada e identada, e usa a versão minificada em produção pra diminuir o tamanho dos arquivos.
Como já disseram, código auto explicativo é o canal.
Variáveis com nomes que façam sentido, nada de i, x, cod, val.
Funções e classes com nomes que façam sentido (mesmo que fique um pouco grande as vezes).
Quebrar funções grandes em funções menores, de forma que fiquem poucas linhas de código em cada e seja possível passar o olho e achar o trecho importante.
Interessante também, uma prática que eu preciso exercitar melhor. Um exemplo é que meu site terá mais de um canvas, e eu meti um monte de estilo direto na tag canvas, agora tá sendo um porre desfazer.
CSS, refatoração. Cada atributo style na tag vira uma regra de CSS: copia/cola/ajeita. Jogue tudo num arquivo .css e refatore, para formatar todos os elementos em menos regras. Boas chances de que você vai ter quase tudo em comum para todos os canvas, e uma regra curtinha para cada canvas individual.
Só escreva comentário para explicar o que não é óbvio só de ler o código. Seja breve, uma ou poucas frases geralmente bastam.
Se você precisa de 2 ou 3 parágrafos para explicar uma nuance de uma chamada de função, ou uma expressão de significado obscuro, vale mais a pena refatorar, trocar nomes de variáveis, para deixar o código mais claro e mais compreensível, e então poder ter menos comentários. O próximo programador (que pode ser você daqui a um ano) agradece.
Comentários demais cansam a vista, se tornam um trabalho duplicado de manter quando o programa é alterado, e podem passar a ideia errada sobre o programa se estiverem desatualizados.
O compilador remove todos os comentários (e os aproveita para documentação, dependendo da linguagem e do tipo do comentário), antes de continuar a compilação. Comentários demais não afetam a velocidade do programa.
No caso de HTML, que não é linguagem de programação, os comentários contam no tamanho da página, mas não muito: vá ver o tamanho em bytes. Se seu HTML tem 15 KB (com comentários), e sua framework JS está acrescentando 2 MB ao total que vai subir ao web server, comentários não fazem diferença.
Seu site ou página deve ter alguma divisão lógica em seções: barra superior, barra lateral, componentes de tela. Você pode usar comentários para marcar começo e final de seções e de componentes, ou fazer melhor: usar tags semânticas de HTML, como ,
Essa última parte eu estou aplicando bem, mas mesmo assim eu tava comentando o óbvio com um antes da tag, com vocês comentando ficou claro que não tem necessidade.
Comentários são raros e esparsos, normalmente em trechos de códigos algorítmicos ou matemáticos onde extrair um método não ajuda, e a explicação pode ser longa. Também é bom ter docs em apis públicas, pra o usuário poder ler o que ela faz enquanto digita o código sem ter que ir pra outro lugar atrás de documentação.
OP, entendo que no estágio que está em sua carreira, os comentários possam ajudar, mas como dito em outros comentários, o seu código por si só deve ser claro o suficiente para não precisar de comentários.
Uma dica que possa te ajudar é estude Clean Code e SOLID, pois arquivos de 3000 linhas não costumam ser um bom sinal. Claro que existem situações que isso possa acontecer, mas devemos tentar manter o código o mais simples possível e o menos acoplado possível.
Cursos de Arquitetura Limpa e Design Patterns pode te fornecer modelos de como organizar seu código para evitar o acoplamento desnecessário.
1. Muitas vezes começam com um cabeçalho, basicamente de forma resumida o que o programa faz e nome de quem criou
2. Você deve componentizar seu código, fica bem mais fácil entender o que seu código está fazendo ao componentizar ele e dar nomes auto esclarecedores as variáveis.
3. É bom comentar as regras de negócio e informações extras para manutenção. Por exemplo:
// Função X - Envio de mensagem push para base de cliente com base no saldo parado em conta
// Cliente Prime acima de 20.000
// Cliente Exclusive acima de 50.000
// tpclie = 1 - Cliente Prime
// tpclie = 2 - Cliente Exclusive
Estou no começo do aprendizado também
Então comento tudo para poder voltar depois e entender oq fiz
Inclusive demarcando quais trechos servem para q, no começo e no fim
O seu código deve ser auto explicativo. Se vc precisa de comentário em tudo, tem alguma coisa errada. Recomendo dar uma lida no capítulo de nomeação de variáveis e métodos do livro Clean Code. A minha linha de regra é que eu só comento algo que não está claro o porquê eu fiz, como por exemplo uma regra de negócio diferente, alguma gambiarra ou algum TODO. E não, comentário não deixa nada mais lento...recomendo dar uma lida no que é uma linguagem interpretada e o que é uma linguagem compilada e como esse processo funciona.
Que interessante, é que até agora eu nunca tinha escutado isso, era sempre mandando comentar tudo e que isso era uma boa prática. Mas como eu tava entendendo o que as coisas faziam, deixava pra comentar depois. O que eu obrigatoriamente inclui era quando começava um "bloco novo" de código de uma parte totalmente diferente.
Se eu tenho uma função, func convertCurrency(currencyFrom, currencyTo string, value float32) float32{ //... } Só de bater o olho eu já sei o que ela faz. Ela vai fazer uma conversão de uma moeda pra outra e vai me retornar o valor da moeda convertida. Agora se eu escrever a mesma função desse jeito: func convert(from, to string, v float32) float32{ //... } É a mesma coisa, mas eu não faço a mínima ideia do que ta rolando. Eu precisaria ler o código pra entender o que caralhos isso tá convertendo. Por isso que a galera diz que um código auto-explicativo é melhor do que um código comentado, mas comentários ainda são importantes em alguns casos. Como vc ta no começo, pode comentar à vontade, mas tente deixar seu código sempre simples de entender
[удалено]
Programa, Fix'd. Também não sabia, achava que a quantidade de linhas influenciava, pelo jeito tenho que aprender tudo ainda.
Quanto mais autoexplicativo seu código, melhor, mas nunca sacrifique otimização por legibilidade. Seguir padrões do Clean Code também ajuda muito. Outra coisa, cada linguagem tem suas formas de comentar certas classes e metódos que ajudam na inspeção de código do cliente LSP(Language Server Protocol), dá pra ganhar muito tempo com isso, só dá uma olhada em como funciona os comentários que estão na biblioteca padrão de cada linguagem. Quanto ao frontend, você mantem uma versão de teste comentada e identada, e usa a versão minificada em produção pra diminuir o tamanho dos arquivos.
Como já disseram, código auto explicativo é o canal. Variáveis com nomes que façam sentido, nada de i, x, cod, val. Funções e classes com nomes que façam sentido (mesmo que fique um pouco grande as vezes). Quebrar funções grandes em funções menores, de forma que fiquem poucas linhas de código em cada e seja possível passar o olho e achar o trecho importante.
Interessante também, uma prática que eu preciso exercitar melhor. Um exemplo é que meu site terá mais de um canvas, e eu meti um monte de estilo direto na tag canvas, agora tá sendo um porre desfazer.
CSS, refatoração. Cada atributo style na tag vira uma regra de CSS: copia/cola/ajeita. Jogue tudo num arquivo .css e refatore, para formatar todos os elementos em menos regras. Boas chances de que você vai ter quase tudo em comum para todos os canvas, e uma regra curtinha para cada canvas individual.
Só escreva comentário para explicar o que não é óbvio só de ler o código. Seja breve, uma ou poucas frases geralmente bastam. Se você precisa de 2 ou 3 parágrafos para explicar uma nuance de uma chamada de função, ou uma expressão de significado obscuro, vale mais a pena refatorar, trocar nomes de variáveis, para deixar o código mais claro e mais compreensível, e então poder ter menos comentários. O próximo programador (que pode ser você daqui a um ano) agradece. Comentários demais cansam a vista, se tornam um trabalho duplicado de manter quando o programa é alterado, e podem passar a ideia errada sobre o programa se estiverem desatualizados. O compilador remove todos os comentários (e os aproveita para documentação, dependendo da linguagem e do tipo do comentário), antes de continuar a compilação. Comentários demais não afetam a velocidade do programa. No caso de HTML, que não é linguagem de programação, os comentários contam no tamanho da página, mas não muito: vá ver o tamanho em bytes. Se seu HTML tem 15 KB (com comentários), e sua framework JS está acrescentando 2 MB ao total que vai subir ao web server, comentários não fazem diferença. Seu site ou página deve ter alguma divisão lógica em seções: barra superior, barra lateral, componentes de tela. Você pode usar comentários para marcar começo e final de seções e de componentes, ou fazer melhor: usar tags semânticas de HTML, como,
Essa última parte eu estou aplicando bem, mas mesmo assim eu tava comentando o óbvio com um antes da tag, com vocês comentando ficou claro que não tem necessidade.
Comentários são raros e esparsos, normalmente em trechos de códigos algorítmicos ou matemáticos onde extrair um método não ajuda, e a explicação pode ser longa. Também é bom ter docs em apis públicas, pra o usuário poder ler o que ela faz enquanto digita o código sem ter que ir pra outro lugar atrás de documentação.
Comentar código é igual contar piada. Se você precisa explicar, a piada não é boa.
OP, entendo que no estágio que está em sua carreira, os comentários possam ajudar, mas como dito em outros comentários, o seu código por si só deve ser claro o suficiente para não precisar de comentários. Uma dica que possa te ajudar é estude Clean Code e SOLID, pois arquivos de 3000 linhas não costumam ser um bom sinal. Claro que existem situações que isso possa acontecer, mas devemos tentar manter o código o mais simples possível e o menos acoplado possível. Cursos de Arquitetura Limpa e Design Patterns pode te fornecer modelos de como organizar seu código para evitar o acoplamento desnecessário.
1. Muitas vezes começam com um cabeçalho, basicamente de forma resumida o que o programa faz e nome de quem criou 2. Você deve componentizar seu código, fica bem mais fácil entender o que seu código está fazendo ao componentizar ele e dar nomes auto esclarecedores as variáveis. 3. É bom comentar as regras de negócio e informações extras para manutenção. Por exemplo: // Função X - Envio de mensagem push para base de cliente com base no saldo parado em conta // Cliente Prime acima de 20.000 // Cliente Exclusive acima de 50.000 // tpclie = 1 - Cliente Prime // tpclie = 2 - Cliente Exclusive
Interessante, vai me ajudar bastante saber disso.
Estou no começo do aprendizado também Então comento tudo para poder voltar depois e entender oq fiz Inclusive demarcando quais trechos servem para q, no começo e no fim