2. Comentários

2.1 Como usar comentários:

Os comentários são utilizados para explicar parte do código, podendo ser uma linha ou um bloco de código, são usados também para desativar temporariamente partes do código sem removê-las, ou para fornecer informações de como funciona.

2.1.1 Comentários de linha única

Esse tipo de comentário ocupa apenas uma linha. Quando são iniciados, o compilador ignora todo o conteúdo escrito até o fim dessa linha.

Aqui estão alguns exemplos de comentários de linha única nas linguagens mais usadas na equipe:

C/C++: Use '//' para iniciar um comentário de linha única

Python:

Use '#' para iniciar um comentário de linha única

2.1.2 Comentários de várias linhas

Esse tipo de comentário pode ocupar várias linha. Possui um ponto de início e fim. Entre esses pontos todo o conteúdo será ignorado.

Aqui estão alguns exemplos de comentários de várias única nas linguagens mais usadas na equipe:

C/C++: Use '/*' define um início e '*/' um fim

Python:

Use ' """ ' define um início e um fim

2.2 Utilizações

Documentar a finalidade de funções e variáveis: Os comentários devem explicar o que uma função faz, quais são seus parâmetros e qual é o seu retorno. Para variáveis, documente seu propósito, significado e contexto em que são utilizadas. Isso ajuda a entender o que uma determinada função ou variável faz sem ter que ler e entender todo o código.

Explicar partes complexas do código: Quando encontrar trechos de código difíceis de entender, adicione comentários explicativos sobre o que está acontecendo e por quê. Comentários são úteis para descrever a lógica por trás de um código complexo, tornando-o mais fácil de entender para outros desenvolvedores.

Adicionar notas sobre decisões de design ou alterações futuras: Comentários podem ser usados para explicar por que uma determinada abordagem foi escolhida, ou para indicar possíveis melhorias ou alterações futuras. Isso pode ser útil para o planejamento e para entender por que certas decisões foram tomadas durante o desenvolvimento.

Descrever algoritmos ou estruturas de dados: Ao implementar algoritmos ou estruturas de dados complexas, é útil adicionar comentários explica digo com o mínimo de palavras possível. Os comentários devem ser claros e diretos, evitando ambiguidades e fornecendo informações relevantes para facilitar a compreensão do código.

Ter uma estrutura de código comentada é uma ótima prática dentro da programação: Uma estrutura de código bem comentada ajuda a organizar e entender o fluxo do programa, tornando-o mais fácil de manter e dar suporte. Isso torna o código mais legível e fácil de manter.

Comentar as chaves ao abrir e fechar: Comentar as chaves ao abrir e fechar blocos de código ajuda a visualizar a estrutura do programa, facilitando a identificação de escopos e evitando erros de lógica. Isso pode ajudar a identificar rapidamente o que uma determinada chave está fechando.

Explicar o motivo daquele valor: Quando valores específicos são atribuídos a variáveis ou constantes, adicione comentários explicando o motivo ou o significado desses valores, tornando o código mais compreensível e transparente .Isso pode ajudar a entender por que um determinado valor foi usado.