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

Os comentários em cinza, explicam cada parte do código

Python:

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

Os comentários em cinza, explicam cada parte do código

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.