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:
This is fine for comments that are inside of functions.
Then there are multiline comments that begin with
/* and end with
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.