## Métodos

Nós vamos agora escrever nossos próprios métodos. Isto é como extender o vocabulário do buggle ensinando novos truques.

Por exemplo, nós vimos num exercício anterior como pedir ao buggle para pegar o baggle na frente dele, e trazê-lo de volta. Se existem vários baggles no tabuleiro, e se nós queremos trazê-los todos para a linha de baixo, você tem que repetir este código várias vezes, ou incluir ele num loop. Em qualquer caso, você deve evitar duplicar seu código para mantê-lo agradável de ler e fácil de entender. Será melhor se o buggle puder obedecer uma ordem `vaiEPega()` assim como entende uma `[!c]avançarUmPasso()[/!][!scala|java|python]avançar()[/!]`.

### Definindo métodos

A sintaxe de [!thelang] para escrever um método simples chamado `vaiEPega` é a seguinte:

    [!java|c]void vaiEPega() {[/!][!python]def vaiEPega():[/!][!scala]def vaiEPega() {[/!]
      ações()[!java|c];[/!]
      ações()[!java|c];[/!]
      eMaisAções()[!java|c];[/!]
    [!java|scala|c]}[/!]

O corpo do método [!java|scala](entre chaves)[/!][!python](o bloco indentado)[/!] será executado quando nós chamarmos o método mais tarde (ou seja, quando nós escrevermos `vaiEPega()` em algum lugar do código). Este corpo do método pode conter tantas instruções quanto você queira, e qualquer construção que nós queiramos (for, while, if, etc). [!java]A palavra-chave `void` significa que este método não retorna qualquer resultado. Por exemplo, o método `estáSobreBaggle()` retorna um resultado, que é um booleano indicando se o buggle está ou não localizado sobre um baggle. Vamos em breve aprender a definir tais métodos também. Por agora, apenas escreva `void` neste local.[/!]

### Documentando métodos

Você deve se esforçar para documentar seu código para mantê-lo legível. Quando você escreve código, fica claro o objetivo e as limitações, mas na maioria das vezes, isto é esquecido. Você rapidamente esquecerá dos detalhes de cada método específico, e vai chegar o dia em que você ficará feliz em ler a documentação. No exemplo seguinte, nós usamos o formalismo específico de [!java]javadoc[/!][!scala]scaladoc[/!][!python]pydoc[/!], um programa que extrai a documentação do código-fonte de [!thelang] e produz páginas html. A principal vantagem é que ele permite que a documentação fique junto ao código. Então, quando você mudar o código, você tem menos chances de esquecer de atualizar a documentação.

comentários em [!java|scala][!java]javadoc[/!][!scala]scaladoc[/!] começam com a marca `/**` (com dois asteriscos). Eles devem ser colocados exatamente antes do método que documentam para a ferramenta encontrá-los.[/!] [!python]comentários pydoc devem ser colocados no começo do corpo do método de forma que a ferramenta possa encontrá-los. Eles devem ser colocados entre `"""`, que marcam strings multilinhas em python.[/!] A primeira linha deve ser uma breve descrição do que o método faz enquanto que as linhas subsequentes devem fornecer qualquer detalhes importantes sobre o método.

    [!java|scala]/**
     *  Vai, recupera o baggle na frente do buggle, e trás de volta
     *
     *  Não verifica se tem paredes, então cuidado para não chamar ele
     *  quando uma parede estiver presente.
     */[/!]
    [!java]void vaiEPega() {[/!]
    [!scala]def vaiEPega() {[/!]
    [!python]def vaiEPega():
      """Vai, recupera o baggle na frente do buggle, e trás de volta.

      Não verifica se tem paredes, então cuidado para não chamar ele
      quando uma parede estiver presente."""[/!]
      ações()[!java];[/!]
      to()[!java];[/!]
      do()[!java];[/!]
    [!java|scala]}[/!]

### Convenções de nomes

A maioria das linguagens de programação proíbe o uso de espaços em indentificadores de métodos e variáveis (=seus nomes). Letras acentuadas são algumas vezes permitidas (como em [!thelang]), mas elas geram problemas de portabilidade entre sistemas operacionais e devem ser evitadas sempre que possível.

Entre todas as linguagens de programação, existem duas convenções para nomear variáveis e métodos. A primeira, consiste em concatenar todas as palavras com apenas a primeria letra de cada palavra em maiúscula. "vai e Pega" se torna vaiEPega(). Isto é chamado "CamelCase" por que identificadores escritos desta forma parecem graficamente com as costas de um camelo. A outra convenção, chamada "snake_case", é escrever todas as palavras em minúsculas, separadas com sublinhados (_). "vai e pega" se torna vai_e_pega().

Que convenção usar é o tópico de discussões acaloradas entre desenvolvedores, mas cada linguagem de programação tem seus próprios hábitos. Em Python, Perl e C, o snake_case é normalmente usado para métodos e variáveis. Java e Scala preferemo lowerCamelCase (só a primeira letra inicial é minúscula) para isto.

A convenção CamelCase é sempre usada no PLM por que este programa foi escrito em Java, então mantivemos o hábito quando inserimos novas linguagens. Mas o fato de os vínculos Python do PLM usarem CamelCase e não snake_case é considerado um bug que será corrigido em algum lançamento futuro.

### Objetivo do exercício

O objetivo deste exercício é escrever um método chamado `vaiEPega()` que faça a mesma coisa que foi feita num exercício anterior (vai para a frente até estar sobre um baggle, pega ele, vai para trás até a posição inicial e solta o baggle).

Este exercício é um pouco diferente por que você não vai precisar escrever todo o código executado pelo buggle. Ao invés disto, você deve apenas escrever um método que será chamado automagicamente quando você clica em Iniciar. Seu buggle vai chamar seu método `vaiEPega()` em cada linha, até que o baggle seja encontrado. [!python|scala]O código para isto já está pronto no método `vaiEPega()`, mas você provavelmente não vai querer mudar isto. [/!] [!java]Você não precisa escrever o código chamado `vaiEPega()`. Ele já está lá automaticamente, mesmo se você não possa vê-lo.[/!]

Mas para isto funcionar, você tem que na verdade escrever este método `vaiEPega()` agora.