@GabsCH Como você pode ver nas respostas anteriores, não há consenso se comentários são uma prática ou se são benéficos ou não.
Há muitas opiniões a respeito, bem fortes inclusive, mas não há fato decidido.
Com o tempo e experiência você terá sua própria opinião a respeito.
O legal, seria ao inves de dizer a opinião baseado em “achismos” o melhor é embasar a opinião. Tem alguma literatura que diga isso?
Em minha opinião, comentário é sempre bom ter para ter uma síntese do que é e para que serve tal coisa, mas não é obrigatório e não deve explicar o método detalhadamente, uma vez que é uma síntese.
Mas eu não uso muito, não.
Seguindo a linha do @andrebmarinho, não, comentários não são boas práticas e só demonstram uma coisa: o código não está bom o suficiente (confuso, complexo, verboso, etc).
Seguindo a linha do mesmo livro citado pelo caro forista, onde o autor é veemente na afirmação de que código bom é auto explicativo.
Porém, isso nos leva a outro ponto: como codificar bem e criar bons códigos? Experiência, meu caro.
Em tempo: para que serve um comentário?
/* Esta classe representa todas as canetas */
public class Caneta{}
Ora, ora, temos um Cheroque Rolmes aqui…
//Este método é responsável pela soma de dois valores numéricos quaisquer e retorna um valor float
public float somar(float n1, float n2) {}
Cheroque em ação de novo
Compreende?
Ou
/* Pelo amor de Deus (se for ateu, pelo amor de Steve Wozniak) não mexa nesse código. Só funciona assim e só desse jeito */
Ou então
/* Este método recebe o código e quantidade de itens do produto, recupera seus dados,
* isola seu valor, calcula o valor do subtotal e processa os juros incidentes sobre o
* mesmo, com base nos tributos pis, cofins e iof, de acordo com a posição do sol e da lua,
* quando do nascimento da era de aquário e do humor do presidente da Ferroviária */
Entende o que quero dizer?
Um comentário só serve para ser óbvio ou tentar explicar algo inexplicável.
Sim experiência sem duvida, programação é um ato que se aperfeiçoa com a prática, porém acho que quando publicamos uma informação no forum como o GUJ tem que entender que esse documento será visualizado milhares de vezes na internet pra pessoas que estão começando, logo a informação precisa ser correta.
Concordo com você Darlan.
Apenas acho que precisamos qualificar nossa opinião e embasar com livros e bons autores, para não prejudicar outros colegas que estão começando.
Mas o livro que você mencionou é baseado na experiência do autor. Não se torna um fato por ele ter escrito um livro baseado na opinião dele.
Essa talk aqui menciona como isso é comum na nossa área (tomar opiniões como fatos) e até mesmo contradiz uma das regras desse livro baseados em experimentos:
Galera, o que o @andrebmarinho está querendo dizer é que o excesso de comentários pode sim deixar o código poluído, agora, a questão de ser boa prática ou não vai depender do programador, tem pessoas que tralham sozinhas e outras em equipes, os comentários são muito úteis em alguns cenários. @andrebmarinho É bom sempre que nós tenhamos humildade e aceitar opiniões adversas!
@GabsCH, um exemplo de aplicação de comentários em HTML e JavaScript em fontes confiáveis:
https://www.w3schools.com/js/js_comments.asp
https://www.w3schools.com/html/html_comments.asp
Basicamente, todo conhecimento da humanidade é baseado em experiências. Porém, seguindo uma metodologia (o tal método científico, onde há sucessivas tentativas, vários erros e muitas anotações sobre).
A questão que o @andrebmarinho se refere é colocar uma opinião sem ter uma base para isso. Ou seja, ou sempre carregou o código de comentário ou nunca coloca comentários em nada.
Boa prática é boa prática em todo lugar. Não importa se estou num time que definiu que todo método deve ter, no mínimo, 4 mil linhas. As boas práticas dizem que não posso ter tantas linhas num mesmo método, pois isso implica em trazer mais coisas que esta funcionalidade deveria comportar.
@darlan_machado, concordo contigo! Mas esse é um assunto para outro tópico, pois está relacionado a design patterns, onde ao invés de termos 1 arquivo de 4mil linhas no ambiente de desenvolvimento, separamos em arquivos e classes diferentes por exemplo!
Eu concordo, o que estou questionando é se houve esse método científico para se chegar a uma conclusão sobre comentários serem benéficos ou não.
Parabéns! Agora você explicou sua colocação. Porém é importante mencionar as fontes.
Apenas pra mencionar os links que você colocou diz apenas como usar o comentário, de forma nenhuma ele diz que “…é boa pratica…”.
O ponto é, o que define boa prática no mundo da programação? Nós somos humanos somos suscetíveis a erros e comentários podem ser úteis, sintaxes como essas com comentários de código podem ajudar de forma visual algumas pessoas que tem dificuldade, ou alguma pessoa com PCD por exemplo, não podemos olhar pro nosso próprio umbigo e achar que o mundo gira em torno de nós. Boas Práticas é tudo que está relacionado ajudar a vida do amiguinho que está do nosso lado. Pense nisso @andrebmarinho! E juntos podemos fazer uma comunidade mais unida.
O que define uma boa pratica? técnicas identificadas como as melhores para realizar determinada tarefa. Toda profissão tem as suas e área de tecnologia não é diferente.
Por exemplo uma nova linguagem de programação foi lançada, parece que tudo é novo né? Só que não, para criar uma nova solução baseada naquela linguagem vamos usar conceitos e boas praticas que já são conhecidos desde os anos 70 por exemplo. Vou dar um exemplo o livro: O mítico homem-mês - Ensaios sobre engenharia de software é uma literatura muito atual, mas sabe quando ele foi escrito? Nos anos 70, sabia? Pois é.
Para finalizar: sabemos que o mercado de T.I tem falta de profissionais, temos que estudar as linguagens mais atuais e Framework, ok! Porém não apenas entender da sintaxe tem que saber aplicar utilizando as melhores boas praticas e isso não esta sendo inventado a cada nova linguagem, já esta devidamente documentada e registrada em anos de testes. Ter conhecimento de boas literaturas técnicas será e é um fator de melhora do profissional conseguir uma boa colocação no mercado de trabalho e assim ajudar o amiguinho.
Sim eu e você e os outros colegas estamos unidos e preocupados com os outros colegas que vão buscar na internet informações e encontrar nossos posts e assim encontrar informação de qualidade e útil e embasada (mencionando as fontes).
Não necessariamente. Um método de 4 mil linhas demandará, com certeza, uma pancada de comentários. Só assim para se tornar minimamente inteligível.
Você já leu esse livro? Clean code do tio ben, bill??? Se sim, você percebe claramente que ele sabe o que fala, escreve com conhecimento de causa. Não é apenas um estudo, um ensaio, é uma obra que contempla uma vivência absurda em desenvolvimento. Assim como o Martin Fowler é fodástico em padrões, por exemplo.
Sim, já li. Eu não duvido da experiência ou conhecimento dele, mas ainda assim é uma opinião.
Uma das coisas que palestra que linkei acima menciona é que muitas das boas práticas que a gente adere são geralmente resultados de oradores carismáticos ao invés de pesquisa e experimentos científicos.
@AbelBueno
Deixa eu te fazer uma pergunta: Você já leu o livro, ok! Mas se fizermos uma enquete aqui e pedir para as pessoas postarem quais livros de engenharia e de boas praticas já leram por exemplo no último ano, você acha que vamos encontrar?
Pois é, até pra você discordar a respeito as pessoas precisam no minimo ter lido as publicações que tratam do assunto, você não acha?
Voltando ao tema do POST: “Devo fazer comentários em todos os meus códigos?”
Se sim? ok, coloque o estudo ou livro ou o que seja pra justificar ou não sua ideia, entendeu onde quero chegar?
Tente ser mais objetivo @andrebmarinho, ficar dando voltas no assunto só confunde a galera, voltando ao assunto relacionado a “boas práticas” e “comentários no código”, eu creio que já chegamos num consenso. Basta entender o ponto de vista que estou apontando aqui. Existem momentos em que os comentários são importantes. Por exemplo: vamos supor que você tenha um trecho em seu código que vai demandar um tempo de processamento alto ou a disponibilidade de um recurso, ou também quando não se consegue colocar um nome em um método que explique o porquê o desenvolvedor tomou aquela decisão… Nesses casos isso pode ser útil e sim, é uma boa prática.
A minha resposta desde o começo vou simplificar para que a @GabsCH, que fez a pergunta, entenda de uma forma mais simples, pois “nosso amiguinho” está começando agora na área da programação!
Sim, eu acredito que entendi seu ponto.
Você está pedindo referência de livros para dar validade as opiniões apresentadas. Acho justo.
O meu ponto é, se você for apresentar um livro como referência, que não seja um livro apenas baseado na opinião de outra pessoa (mesmo que essa pessoa seja o Robert C. Martin!).
Como eu desconheço estudos utilizando método científico sobre esse assunto e conheço gente com opinões pró e contra, eu considero isso uma questão de opinião. Mesmo que uma opinião seja muito mais popular que outra.
Obrigada por lembrar que sou uma iniciante, me ajudou a entender o emaranhado de informações novas. É difícil se situar com tantas informações e opiniões muitas vezes fortes sobre um assunto aparentemente simples.
@jrbyte thank you
A questão é simples: o comentário vai deixar o programa mais fácil de ser entendido ou só adicionar ruido?
Isso vale não só pra avaliar se vai comentar ou não, como também pra avaliar o que você vai escrever no comentário.