Fórum MixMods

Tópico antigo: http://brmodstudio.forumeiros.com/t5984-5-comentarios

Concluindo esta parte você vai:
Saber responder o que são "comentários", o motivo de serem importantes e como usá-los nos seus scripts;
Receber dicas do compartilhamento do seu código.

Comentários
"Comentários" na programação são linhas utilizadas para comentar (anotar) alguma parte do código com o objetivo de informar o que aquilo faz.

Comentários são úteis tanto para você quanto para terceiros entenderem o seu source code — o seu código fonte.

Você
De início você provavelmente não notará a importância do ato de "comentar" o seus códigos, já que você estará fazendo coisas simples e pequenas demais. Mas quando você estiver criando longos códigos de muitas linhas, acredite, se você não comentar irá se perder.

O fato é que, diferente do que leigos pensam, mesmo programadores experientes não olham para um código e de cara entendem tudo o que está lá, mesmo se o código for dele mesmo (e que seja significantemente antigo a ponto de perder a memória).

Imagem

(english)

A verdade é que mesmo os experientes precisam de explicações para entender o código mais rapidamente, e geralmente, para entender uma parte complexa de um código onde não está bem comentada é necessário ficar relendo grandes pedaços para lembrar/entender o que aquilo faz.

Outros
Quando você está produzindo algum script você muito provavelmente está só pensando no público alvo, que neste caso será o jogador que instalará o seu mod e jogará, onde "comentar" os seus códigos não fazem diferença, mas pode sim fazer diferença caso você queira divulgar o seu código, deixá-lo aberto para o público (outros programadores) verem, analisarem, te darem dicas, ensinar você a aprimorar seus trabalhos, ou até mesmo para quando você está com algum problema num código e quer pedir ajuda, os comentários no seu código facilitarão o trabalho do programador de entender o seu código e te ajudar.

Open Source
Eu inclusive encorajo você de sempre compartilhar o source code (código fonte) dos seus códigos. Não deixe que seu trabalho não seja aprimorado, libere seus códigos como "código aberto" (open source). Alguém mais experiente que você pode te dar dicas de como melhorar o seu código e você aprender mais, ou alguém menos experiente que você pode ver o seu código e aprender com ele.
Você pode divulgar como bem querer, como usando Gist ou incluindo no próprio download; nas próprias publicações de download etc.

Como aplicar comentários?
No GTA3script a aplicação dos comentários é igual a maioria das linguagens de programação.

Código: Selecionar tudo

// Este é um comentário de uma linha.

/*
Este é um comentário
de múltiplas
linhas.
*/

// Mais uma linha de comentário,
// e mais outra.

Por exemplo, um comentário do Galvão Bueno:

Código: Selecionar tudo

CREATE_CAR NRG500 x y z my_bike // Tá certo isso, Arnaldo?

Certíssimo, Galvão!

Outro exemplo, no script do passo anterior:

Código: Selecionar tudo

{ // Abri um escopo
NOP // Um comando sem operação que serve para preencher o topo vazio

// Abaixo um código que ficará "loopando" (repetindo) infinitamente:
main_loop: // Uma label
WAIT 0     // Para este script, processa os outros, processa o jogo e espera 0 milésimos
PRINT_STRING_NOW "Sup world." 1000 // Opcode da CLEO para mostrar um texto na tela
GOTO main_loop // Voltar para a label "main_loop" acima, assim criando uma repetição, um loop
} // Fechei um escopo

EnglishAbrir

Código: Selecionar tudo

{ // I opened a scope
NOP // A command without operation that serves to fill the empty top

// Bellow a code that will be "looping" (repeating) infinitely:
main_loop: // A label
WAIT 0     // Stop this script, process others, process the game and wait 0 milliseconds
PRINT_STRING_NOW "Sup world." 1000 // CLEO opcode to show a text on screen
GOTO main_loop // Go back to label "main_loop" above, so creating a repetition, a loop
} // I closed a scope

Note que você pode não entender o que está explicado nos comentários acima. Mas você entenderá tudo isso ao decorrer deste tutorial! Só estou te mostrando para começar a ficar familiarizado com os códigos e a lógica do scripting.

Note também que o exemplo acima é um uso exagerado de comentários, afim de explicar cada linha. Provavelmente você nunca fará isso no seu código (nunca mesmo!). Só adicione comentários quando realmente precisar! Muitos comentários pode deixar o código confuso e poluído, assim mais atrapalhando do que ajudando.
A dica é comentar somente partes que você acha que irá passar mais tempo mexendo ali (mais importantes, complexas etc). Não comente coisas óbvias! Se aquilo é óbvio para você e você sabe que você sempre entenderá quando ler aquilo, não comente!

Afeta algo?
Em questões de afetar o desempenho, absolutamente nada! Pois comentários são ignorados pelo compilador e não vão para o produto final. Os comentários só são utilizados pelo programador que está lendo eles — seja você, ou alguém que esteja lendo seu source code.

Portanto, não mudará nada no tamanho do arquivo compilado e nada no processamento. Você pode usar o quanto quiser, mas só quando você achar necessário. Na real, há programadores profissionais onde 30% dos seus sources são só comentários.

"Você disse na introdução que o tutorial seria divertido. Já estou ficando entediado(a)!"
Na próxima parte do tutorial você finalmente começará a entender como um script funciona dentro do jogo!

Próxima parte:
6. Princípios de funcionamento e loops

Fórum MixMods

5. Comentários

5. Comentários