It can be easy to forget that code doesn’t live in isolation. It’s picked up and modified by others. It’s investigated and it evolves over time - by other people.

It’s essential to leave behind well documented code so that not only do you enable your teammates to work on it autonomously - but so that your future self can understand why and how your feature is written.

Comments in PHP

We have 2 ways of creating comments in PHP, the first is commenting for a single line:

function greeting($name) {
  // produces strings like 'Hello Dylan'
  return 'Hello ' . $name;
}

This is fine for comments that are inside of functions.

Then there are multiline comments that begin with /* and end with */:

/**
 * Greets the user
 * 
 * @param $user
 * @return string
 */
function greeting($name) {
  return 'Hello ' . $name;
}

You can see how this can be more formal, but essentially it creates a “blocked” comment. Anything between the /* and the /* characters will be skipped by the PHP interpreter.

You’ll commonly see multiline comments describe the class, it’s variables and functions.

Comments in Ruby

For all of the other flexibility Ruby gives you - this time they only provide 1 way to do a thing. Like Python, Ruby’s comment keyword is #:

def greet(name)
  # productions Strings like 'Hello Dylan'
  return 'Hello ' + name
end

However, it’s still good practice to leave multiline comments describing functions. The only difference being that you use 1 character for all comments instead of 2 different options:

# Greets the user
#
# @param name
# @return String
def greet(name)
  return 'Hello ' + name
end

It’s essentially the same idea, but with no opening or closing tags to worry about.