Methods

We will now write our own methods. It somehow comes down to extending the buggle vocabulary by teaching it new tricks.

For example, we saw in a previous exercise how to ask the buggle to go get the baggle in front of it, and bring it back. If there is several baggles on the board, and if we want to bring all of them on the bottom line, you have to repeat this code several times, or include it in a loop. In any case, you should avoid to duplicate your code to keep it pleasant to read and easily understandable. It would be better if the buggle could obey an goAndGet() order just like it understands a [!c]stepForward()[/!][!scala|java|python]forward()[/!] one.

Defining methods

The [!thelang] syntax to write a simple method called goAndGet is the following:

[!java|c]void goAndGet() {[/!][!python]def goAndGet():[/!][!scala]def goAndGet() {[/!]
  actions()[!java|c];[/!]
  to()[!java|c];[/!]
  do()[!java|c];[/!]
[!java|scala|c]}[/!]

The method body [!java|scala|c](between curly braces)[/!][!python](the indented block)[/!] will be executed when we call the method later on (that is, when we write goAndGet() somewhere in our code). This method body can contain as many instructions as you want, and any construction we saw so far (for, while, if, etc). [!java|c]The void keyword means that this method does not return any result. For example, the isOverBaggle() method does return a result, which is a [!c]int[/!][!java]boolean[/!] indicating whether or not the buggle is located over a baggle. We will soon learn to define such methods too. For now, just write void at this location.[/!]

Documenting methods

You should strive to document your code to keep it readable. When you write it, its purpose and limitations are clear to you, but most of the time, this does not last for long. You will soon forget about the details of every specific method, and this day you will be happy to read its documentation. In the following example, we use the specific formalism of [!java]javadoc[/!][!scala]scaladoc[/!][!python]pydoc[/!], a program that extracts the documentation of [!thelang] source code to produce html pages. The main advantage is that it allows to keep the documentation near to the code. So, when you change your code, you have less chances to forget to update the documentation.

[!java|scala][!java]javadoc[/!][!scala]scaladoc[/!] comments begin with the /** marker (with two asterisks). They must be placed right before the method they document for the tool to find them.[/!] [!python]pydoc comments should be placed at the beginning of the method body so that the tool finds them. They should be placed between """, which mark multi-line strings in python.[/!] The first line should be a brief description of what this method does while any subsequent lines should provide any important details about the method.

[!java|scala]/**
 *  Go, retrieves the baggle in front of the buggle, and brings it back 
 *
 *   Does not check for walls, so be careful to not call it when walls are present.
 */[/!]
[!java]void goAndGet() {[/!]
[!scala]def goAndGet() {[/!]
[!python]def goAndGet():
  """Go, retrieves the baggle in front of the buggle, and brings it back.

  Does not check for walls, so be careful to not call it when walls are present."""[/!]
  actions()[!java];[/!]
  to()[!java];[/!]
  do()[!java];[/!]
[!java|scala]}[/!]

Naming conventions

Most programming language forbid the use of spaces in method and variable identifiers (=their names). Accented letters are sometimes allowed (as in [!thelang]), but they can lead to portability issues between operating systems and should thus be avoided when possible.

Across all programming languages, there is two main conventions to name variables and methods. The first one, consists in concatenating all words with only the first letter of each word in upper case. "go and get" becomes goAndGet(). It is called CamelCase because identifiers written this way graphically remind of a camel back. The other convention, called snake_case, is to write every words in lower case, separated with underscores symbols (_). "go and get" becomes go_and_get().

Which convention to use is the topic of heated discussion across developers, but each programming language has its own habits. In Python, Perl and the C language, the snake_case is often used for methods and variables. Java and Scala prefer the lowerCamelCase (the very first letter is lower case) for that.

The CamelCase convention is used everywhere in PLM because this program is written in Java itself, so we kept our habits when adding new languages. But the fact that the Python bindings of PLM use the CamelCase instead of the snake_case is considered as a bug that we will fix in further releases.

Exercise goal

The goal of this exercise is to write a method called goAndGet() which does the same than in a previous exercises (move forward until over a baggle, pick it up, move back to initial position, drop baggle).

This exercise is a bit different because you will not write all of the code executed by the buggle. Instead, you should only write one method that get called automagically added when you click on Start. Your buggle calls your goAndGet() method on each row, until the baggle is found. [!python|scala]The code for that is already provided under the goAndGet() method, but you probably don't want to change it.[/!] [!java]You don't need to write the code calling goAndGet() yourself. It's automagically there already, even if you cannot see it.[/!]

But for that to work, you have to actually write this goAndGet() method now.