Você pode até achar o título engraçado, porque o assunto é simples e básico, mas acredite, tem muita gente que tem dúvidas em relação aos comentários, tem muita gente que não usa (e deveria), e também tem gente que não sabe o que é, e nunca viu.
Se você se encaixa em um dos perfis acima, ou não, pode se interessar pela utilidade que os comentários tem para nós, programadores.
Acredite ou não, podemos considerar os comentários como um dos nossos melhores amigos quando o assunto é programar. Um comentário tem como função documentar o código escrito, afim de que no futuro, você saiba o que um certo trecho de código faz, e porque ele faz. E de quebra ele ajuda na boa visualização do código.
A princípio podemos pensar que não existe necessidade de se comentar um projeto, pois no momento em que estamos escrevendo o código, tudo está claro e fresco em nossa mente. Mas o problema meu amigo, aparece meses depois, quando você tem que fazer “aquela” alteração no código. O que você vê é um emaranhado de letrinhas, e realmente fica complicado se achar ali. E quando você encontra o que quer… não sabe como funciona, ou porque o código é grande e você vai perder horas “garimpando” aquilo ali, ou porque ele não se autoexplica o suficiente (e normalmente ele deveria, mas…).
É aí que o nosso parceiro entra. Se o código estiver bem comentado, além da visualização ficar mais clara, pois não tá tudo espremido, você vai ter uma explicação do que aquele determinado trecho faz.
Existem 3 tipos de comentários em grande parte das linguagens (se souberem de mais algum, me avisem): comentário em linha, comentário em multilinha, e o último, conhecido por javadoc.
O comentário em linha (//) é o mais simples e, pelo menos no meu caso, um dos mais usados. Ele serve para comentários simples, normalmente para comentar uma linha de código.
Vejamos o seguinte trecho de código:
1 2 3 4 5 | public function startup(application:BaseApplication):void { Debugger.showMessage("Application Pre-initializing", Debugger.PROCESS); this.sendNotification(ApplicationFacade.PREINITIALIZE, application); } |
Se você não está por dentro do código como um todo, dificilmente irá entender este trecho (apesar de pequeno, imagine um grande).
Já, com as linhas devidamente comentadas, fica mais fácil de entender o que se passa.
1 2 3 4 5 6 7 8 | public function startup(application:BaseApplication):void { // Exibindo mensagem no debbuger. Debugger.showMessage("Application Pre-initializing", Debugger.PROCESS); // Notificando o sistema que a aplicação está sendo inicializada. this.sendNotification(ApplicationFacade.PREINITIALIZE, application); } |
Obviamente, se o seu comentário não for claro o bastante, de nada adianta.
Como vimos, o comentário de linha inicia com //, ocupa apenas uma linha, e é muito útil para comentar linhas de código e pequenos trechos. Eu sempre que posso comento ao máximo o meu código, linha a linha mesmo. Parece exagero, mas isso ajuda a mim, e às pessoas que trabalham com o meu código.
O segundo tipo de comentário, o multilinha, que como o nome já diz, ocupa mais de uma linha, e serve para longas descrições a respeito de um trecho de código.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | override public function execute(notification:INotification):void { // Enviando mensagem para o debugger. Debugger.showMessage("ApplicationStartup command executing...", Debugger.PROCESS); /* Registrando ApplicationProxy, responsável por obter as informações sobre o carregamento da aplicação. */ this.facade.registerProxy(new ApplicationProxy()); // Obtendo proxy registrado. var proxy:ApplicationProxy = this.facade.retrieveProxy(ApplicationProxy.NAME) as ApplicationProxy; // Monitorando carregamento da aplicação. proxy.watchApplicationLoading(notification.getBody() as BaseApplication); /* Registrando BaseApplicationMediator, responsável por "gerir" os componentes de visualização, e por dar feedback para a aplicação conforme as ações dos usuários ocorrem sobre estes componentes. */ this.facade.registerMediator(new BaseApplicationMediator(notification.getBody())); } |
O comentário de multilinha como você está vendo, inicia com /* e só encerra quando encontrar o */. Tudo que estiver entre /* */ será considerado comentário. Podemos com ele também comentar nossos métodos.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | /* Executa o comando. Este método é chamado internamente pelo sistema. */ override public function execute(notification:INotification):void { // Enviando mensagem para o debugger. Debugger.showMessage("ApplicationStartup command executing...", Debugger.PROCESS); /* Registrando ApplicationProxy, responsável por obter as informações sobre o carregamento da aplicação. */ this.facade.registerProxy(new ApplicationProxy()); // Obtendo proxy registrado. var proxy:ApplicationProxy = this.facade.retrieveProxy(ApplicationProxy.NAME) as ApplicationProxy; // Monitorando carregamento da aplicação. proxy.watchApplicationLoading(notification.getBody() as BaseApplication); /* Registrando BaseApplicationMediator, respons‡vel por "gerir" os componentes de visualização, e por dar feedback para a aplicação conforme as ações dos usuários ocorrem sobre estes componentes. */ this.facade.registerMediator(new BaseApplicationMediator(notification.getBody())); } |
O terceiro e último tipo de comentário, é conhecido como Javadoc. Javadoc é uma ferramenta de documentação para Java. Esta ferramenta lê a classe criada, e através de um tipo específico de comentário gera uma documentação daquela classe. Hoje existem diversas ferramentas, para diversas linguagens, que usam o estilo de comentário do javadoc para gerar documentações.
A vantagem que existe em se utilizar comentários em javadoc é que você pode ter uma documentação de todas as suas classes. Isso é muito importante, principalmente em grandes projetos. Ao documentar suas classes, você tem uma forma simples, prática e rápida de navegar por entre os diversos métodos e propriedades existentes.
No AS3 temos o ASDoc, que usa a mesma sintaxe do Javadoc. Um pequeno exemplo:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | package app.controller { import app.BaseApplication; import app.model.ApplicationProxy; import app.utils.Debugger; import app.view.BaseApplicationMediator; import org.puremvc.as3.interfaces.ICommand; import org.puremvc.as3.interfaces.INotification; import org.puremvc.as3.patterns.command.SimpleCommand; /** * A classe ApplicationStatupCommand prepara os elementos de dados e visualização necessárias * para a inicialização da aplicação. * * @author Mozart Petter */ public class ApplicationStartupCommand extends SimpleCommand implements ICommand { /** * Executa o comando ApplicationStartupCommand. O método execute é chamado internamente pelo * sistema. Ele inicia o <code>Proxy</code> da aplicação e registra o <code>Mediator</code> * responsável pela visualização. * * @param notification Objeto <code>INotification</code> recebido pelo sistema, contendo * a notifição enviada. * @return void */ override public function execute(notification:INotification):void { // Enviando mensagem para o debugger. Debugger.showMessage("ApplicationStartup command executing...", Debugger.PROCESS); /* Registrando ApplicationProxy, responsável por obter as informações sobre o carregamento da aplicação. */ this.facade.registerProxy(new ApplicationProxy()); // Obtendo proxy registrado. var proxy:ApplicationProxy = this.facade.retrieveProxy(ApplicationProxy.NAME) as ApplicationProxy; // Monitorando carregamento da aplicação. proxy.watchApplicationLoading(notification.getBody() as BaseApplication); /* Registrando BaseApplicationMediator, responsável por "gerir" os componentes de visualização, e por dar feedback para a aplicação conforme as ações dos usuários ocorrem sobre estes componentes. */ this.facade.registerMediator(new BaseApplicationMediator(notification.getBody())); } } } |
Muito parecido com o comentário multilinha certo? A pequena diferença é que um comentário javadoc/asdoc começa com /** e termina com */.
A documentação gerada pelo ASDoc é no mesmo formato da documentação das classes do Flash/Flex/AIR. Existem algumas IDEs como a FlashDevelop que tem um gerador de ASDoc nativo. Você pode encontrar informações sobre o ASDoc e como gerar a documentação nos links abaixo:
É isso aí pessoal, espero que vocês tenham gostado, e que agora passem a comentar o seu código (ou o bicho papão vai te pegar), deixando ele muito mais claro e fácil de entender.
Mozart, é bom ver você voltar a postar mais seguidamente. Nós, profissionais ou não, precisamos e fazemos bom uso da sua orientação. Os “coments” passarão a fazer parte do meu dia-a-dia. Gracias!
Bacana Cara….
Comentários nunca é demais. Principalmente para pessoas estranhas ao seu código, pois ninguém pensa igual. Peça para o pessoal de uma sala desenhar uma árvore, nenhuma sai igual. Cada um tem a sua idéia de árvore. Funciona com lógica de programação…
Lembrando que no beta do Flex 4 os comentários tipo ASDoc aparecem no auto help quando você está trabalhando com uma classe que você criou. Mais um incentivo para o pessoal comentar…
Abraço !
Olá Mozzart, primeira vez que to visitando teu blog, to iniciando em AS3 e to procurando primeiro o basico, pois trabalhei muito tempo com as2 e é mais doque hora de migrar, parabens pelo seu blog, vou visitar com frequencia. Se voce tiver alguns sites em que eu possa encontrar o basico do as3 que ensine de forma correta eu agradeço.
abraços.
Olá Jeff,
Seja bem-vindo. Cara, quando eu comecei com o AS3 vindo do AS2, o que eu fiz foi me abraçar na documentação mesmo, até porque não tinha muito material, então eu não tenho muito conhecimento sobre artigos existentes. Existe um texto meu introdutório que eu estarei republicando aqui no blog em breve. Por enquanto o que eu posso te passar de referências está aí embaixo:
http://livedocs.adobe.com/flex/2/langref/migration.html
http://help.adobe.com/en_US/AS3LCR/Flash_10.0/
Abraço