Understanding the Drupal Coding Standards

Video loading...

  • 0:01
    Understanding the Drupal Coding Standards
  • 0:03
    with Joe Shindelar
  • 0:05
    If you've ever submitted a patch to Drupal Core,
  • 0:08
    or any of the many contributed modules,
  • 0:10
    or even just worked with other developers who
  • 0:12
    do Drupal development, you've likely encountered the Drupal coding
  • 0:16
    standards, a set of guidelines that dictate the formatting and style
  • 0:19
    to use when writing code for Drupal.
  • 0:22
    As a community, we tend to be pretty strict about following the coding
  • 0:25
    standards.
  • 0:26
    So understanding what they are, and why they exist,
  • 0:28
    and how to follow them is important.
  • 0:30
    In this tutorial, I'm going to talk about what coding standards are,
  • 0:34
    why they exist and how they're helpful to a community like Drupal,
  • 0:38
    where you can find more information about Drupal's coding standards.
  • 0:41
    And finally, I'm going to walk through most
  • 0:43
    of the basics of the Drupal PHP coding standards.
  • 0:47
    So let's go ahead and get started.
  • 0:50
    I like this quote that describes what coding standards are
  • 0:53
    and why they exist.
  • 0:55
    It says, "The quality of your code is not just in its execution,
  • 0:58
    but also in its appearance."
  • 1:00
    I read a book a couple of years ago about writing good code.
  • 1:04
    And in it, the author of the book is comparing hackers and painters.
  • 1:07
    And he talks a lot about the similarities
  • 1:10
    that people that are of a mindset of being a good hacker
  • 1:13
    share with those who are also good painters.
  • 1:15
    And one of the things was attention to detail-- always
  • 1:18
    being picky about the way things look, following formatting,
  • 1:21
    and making sure that you're consistent.
  • 1:23
    That's really what coding standards all about-- paying attention
  • 1:26
    to detail and being consistent.
  • 1:29
    So at a really high level, what is a coding standard?
  • 1:33
    Coding standards is a set of guidelines regarding naming
  • 1:36
    conventions and the use of white space
  • 1:38
    and the format to follow when writing for loops
  • 1:40
    and if statements, how to name variables, and what function names
  • 1:43
    should be.
  • 1:44
    It's all about defining, as a group of people who are writing code
  • 1:48
    together, we're always going to format
  • 1:50
    our code following the same pattern.
  • 1:53
    If you ever wrote a paper in high school or college,
  • 1:55
    you were probably required to follow a standard,
  • 1:57
    like the APA or MLA guidelines.
  • 2:01
    These guidelines exist and they say, like,
  • 2:02
    this is how you should indent your paragraph.
  • 2:04
    This is the number of spaces that you should
  • 2:06
    put between sentences, and so forth.
  • 2:08
    Though if you follow those guidelines,
  • 2:10
    it allows people that are reading your paper to focus on the content
  • 2:13
    of the paper and not differences in formatting styles and so forth.
  • 2:17
    If we pay attention to detail and we follow the standards,
  • 2:20
    we allow people the freedom to focus on the content
  • 2:23
    and not necessarily spend a lot of time thinking
  • 2:25
    about spacing and formatting issues.
  • 2:29
    Coding standards encourage readability.
  • 2:31
    They make it so that the code that we write
  • 2:32
    is easier for others who are also writing the same type of code
  • 2:36
    to read what we've written and follow
  • 2:37
    what we're trying to do in that code.
  • 2:39
    Code that follows coding standards is
  • 2:41
    inherently more maintainable code.
  • 2:44
    It means that it's easy for the next person who comes along and has
  • 2:47
    to look at your code to figure out what's going on
  • 2:49
    and also follow that same standard, especially
  • 2:51
    if those standards are documented.
  • 2:53
    There's a known, this is how we should write code.
  • 2:56
    Coding standards make it easier for ourselves and for others who
  • 2:59
    are reviewing our code to spot errors because we know what
  • 3:03
    the standard should look like, and we've learned it
  • 3:05
    and we've kind of internalized, "Oh man,
  • 3:08
    this is what the PHP should look like."
  • 3:10
    If it doesn't, I immediately gravitate
  • 3:12
    towards that line or those couple of lines.
  • 3:14
    In general, if they are not in line with the standards,
  • 3:17
    it's also an indicator that there might be something a little bit
  • 3:19
    weird going on there, and helps me find errors.
  • 3:21
    Coding standards mean that we're all on the same page.
  • 3:24
    And this makes it easy for me to do things like review your code.
  • 3:27
    And if you had your coding standard and I had my mine
  • 3:31
    and we both formatted our code in different ways,
  • 3:33
    I might call you out and say you know what?
  • 3:35
    You need to have a period at the end of this comment.
  • 3:37
    And you might say, well, in my world I
  • 3:39
    don't put periods at the end of comments.
  • 3:41
    And this can cause tension between a team
  • 3:43
    of developers that is unnecessary.
  • 3:45
    If we have a documented standard that we all follow,
  • 3:48
    we can always just point at that standard and say, see?
  • 3:50
    The standard says there is supposed to be
  • 3:52
    a period at the end of the comment.
  • 3:53
    Because that's there and yours is missing, we need to add it.
  • 3:57
    In a community sense coding standards also
  • 3:59
    encourage collective ownership of the code.
  • 4:01
    It means that we're all concerned about the details together
  • 4:05
    and that we all care about the way that our code looks
  • 4:07
    and the way that it's formatted and the way that it works.
  • 4:10
    This is important for a large open source community like Drupal.
  • 4:14
    You might be thinking to yourself, OK.
  • 4:16
    Coding standards-- aren't these just little details
  • 4:19
    that don't really matter?
  • 4:21
    Well, yes and no.
  • 4:22
    I mean, from the perspective of the computer that has to run the code,
  • 4:25
    it could care less.
  • 4:26
    The computer compiles your code down to byte code.
  • 4:29
    By that time, it looks nothing like your original code.
  • 4:32
    It doesn't care about white space or comments and so forth.
  • 4:34
    And that code will run the same no matter
  • 4:36
    what it looks like in the editor or however
  • 4:38
    you've chosen to edit the code.
  • 4:42
    However, there's a lot of reasons that these details are important.
  • 4:46
    One of them, and probably the biggest one to me,
  • 4:48
    is that paying attention to details shows your coworkers
  • 4:51
    and your clients that you care about the details.
  • 4:54
    If you follow the coding standards, you're ensuring to the people
  • 4:57
    that you're working with that you respect people who can do
  • 5:01
    high-quality work, and that you're interested in doing
  • 5:03
    high-quality work yourself.
  • 5:05
    Take, for example, reading a book.
  • 5:07
    If there's a typo in a book or a paper that we're reading,
  • 5:09
    it's generally pretty easy to forgive it.
  • 5:11
    And if there's one or two typos, it's not that big of a deal.
  • 5:15
    It's not distracting.
  • 5:17
    However, if there's a lot of typos or multiple errors
  • 5:21
    within a single book or a single paper,
  • 5:23
    it starts to become fairly distracting.
  • 5:25
    And we began to question things like the author's writing ability.
  • 5:29
    And as soon as we're questioning the writing ability of the author,
  • 5:31
    we're no longer thinking about the content of the book
  • 5:33
    and we're more thinking about how is this author able to keep all
  • 5:36
    of the characters straight if they can't even keep their "their"
  • 5:40
    and "there" straight.
  • 5:41
    So that's a little bit about why coding standards.
  • 5:44
    Let's talk about the Drupal coding standards.
  • 5:46
    The Drupal coding standards are-- the canonical source
  • 5:49
    of documentation for these is on drupal.org
  • 5:51
    at drupal.org/coding-standards.
  • 5:55
    We can take a look at that really quick.
  • 5:58
    So in my browser I've pulled up that page.
  • 6:00
    You can see this is the beginning of the coding standards documentation.
  • 6:03
    It's a really long page.
  • 6:04
    It talks a little bit about why coding standards are important
  • 6:06
    and you would want to follow them.
  • 6:08
    And then it starts to go through all of the things
  • 6:10
    that make up our coding standards. And you can see there's quite a bit.
  • 6:13
    We're going to talk about most of these, indenting and white space,
  • 6:15
    control structures, arrays, and so forth.
  • 6:18
    If you're ever curious, you could say, you know what?
  • 6:20
    I want to know more about function calls.
  • 6:22
    And the coding standards you come here, click on Function Calls,
  • 6:25
    and it'll give you an explanation of what the coding standard is
  • 6:29
    and then some examples of how to follow it.
  • 6:32
    This is a really great page if you're
  • 6:34
    interested in learning more about the coding standards.
  • 6:36
    At the bottom of this page, there's also links
  • 6:39
    to some additional standards-related things,
  • 6:42
    like how Drupal uses naming conventions and so forth, which
  • 6:46
    really are part of our standard as well.
  • 6:47
    We have standard naming conventions for things
  • 6:49
    like modules and functions and so forth.
  • 6:53
    Take a look at those.
  • 6:54
    We're going to be talking about the PHP coding standards,
  • 6:56
    because they're the ones that are the most set in stone
  • 6:58
    and you'll run into a lot.
  • 6:59
    There's also CSS coding standards.
  • 7:01
    I recommend if you're ever writing CSS for a Drupal theme
  • 7:04
    or module you also take a look at the CSS coding standards.
  • 7:09
    So back to our presentation.
  • 7:13
    One thing to note about the Drupal coding standard
  • 7:15
    is that the Drupal coding standard is version-independent.
  • 7:18
    That means that it's always current.
  • 7:20
    Whatever version of Drupal you're working with,
  • 7:22
    you should follow the standard that's documented
  • 7:24
    at /coding-standards.
  • 7:26
    And it's the same for Drupal 6, Drupal 7, Drupal 8, and so forth.
  • 7:30
    If there are ever differences, those will be noted in the documentation,
  • 7:33
    but it's really rare.
  • 7:36
    So let's take a look at the things that make up our coding standards.
  • 7:40
    First off, some very basic general things.
  • 7:43
    If you're writing a PHP file in Drupal,
  • 7:46
    here's some things that you need to know.
  • 7:48
    The Drupal coding standard dictates that we always use full PHP syntax.
  • 7:53
    So instead of using the shorthand less than question mark indicator
  • 7:58
    for opening a PHP statement, we always use the full
  • 8:02
  • 8:07
    In general, if the file contains only PHP,
  • 8:10
    so like a .module file, for example, that contains nothing
  • 8:13
    but PHP code, we leave out the trailing closing
  • 8:16
    tag of the PHP statement.
  • 8:18
    Now this is a normal thing.
  • 8:19
    We leave that out.
  • 8:20
    We also make sure that we leave a new line at the end of the file.
  • 8:23
    So every .module file should have an opening PHP tag, a bunch of PHP
  • 8:27
    code, and then a blank line at the end with no closing PHP tag.
  • 8:32
    We always use two spaces for indentation.
  • 8:38
    Drupal uses the Unix new line character, so make sure
  • 8:41
    you configure your editor to use a Unix line
  • 8:44
    feed instead of a Windows or Mac line feed.
  • 8:50
    In addition to that, we favor that whenever possible,
  • 8:54
    code sticks to 80 characters per line.
  • 8:56
    As we'll see with comments, this is definitely a rule.
  • 8:58
    Comments should wrap at 80 characters.
  • 9:01
    With code, we try to keep it condensed to 80 characters.
  • 9:03
    But of course, there's places where a line of code
  • 9:06
    will stretch beyond 80 characters.
  • 9:10
    When in doubt, more lines is better than one long line of code.
  • 9:16
    Coding standards for hooks-- this really comes down
  • 9:18
    to the documentation standard here.
  • 9:21
    And that's just that whenever you're implementing a hook in Drupal,
  • 9:26
    the standard is to document it by including the doc block at the top
  • 9:30
    that reads Implements, and then the name of the hook.
  • 9:32
    You don't really need to include any other documentation.
  • 9:35
    And the assumption is that someone that wants to understand what
  • 9:37
    this code does can look at the documentation for that hook.
  • 9:40
    Of course, you would want inline comments explaining your specifics,
  • 9:43
    but there's no need to write additional documentation in the doc
  • 9:47
    block here.
  • 9:48
    Coding standards for operators-- so things like
  • 9:51
    equals sign and operators that perform
  • 9:54
    operations on any variable in your code.
  • 9:56
    We always use one space on either side of the operator.
  • 10:00
    So there's a couple examples here.
  • 10:02
    Variable equals 2-- the top example is the good.
  • 10:06
    Follows the coding standards.
  • 10:07
    You can see there's a white space on either side of the equals sign.
  • 10:11
    The second doesn't have that white space and is a bad example.
  • 10:14
    This is also true when using operators inside
  • 10:16
    of control structures, like an "if" statement.
  • 10:20
    Rule of thumb-- spaces on either side of your operator.
  • 10:24
    This is also true of concatenation operators.
  • 10:27
    Coding standards for control structuress--
  • 10:29
    so if you're writing an if statement or a switch statement or a
  • 10:32
    for each loop, here's some good advice to follow.
  • 10:36
    You should always use a space between a keyword and the opening
  • 10:39
    parentheses that designates the expression
  • 10:41
    for your control structure.
  • 10:43
    So if, space, expression.
  • 10:45
    Else if, space, expression.
  • 10:49
    We always use curly braces, even when they're optional.
  • 10:53
    There are some cases in PHP where, for example, if you have an if
  • 10:56
    statement with an expression and then it only does a single thing
  • 11:00
    underneath it, you can leave out the curly braces.
  • 11:02
    However in Drupal, for readability we always use curly braces.
  • 11:08
    We don't use spaces inside of keywords.
  • 11:10
    This is primarily for the else if keyword, but instead of saying
  • 11:13
    else, space, if, we always leave that space out.
  • 11:17
    We leave out any extra space on the inside of parentheses.
  • 11:21
    A lot of times you'll see people write PHP code where it would be,
  • 11:24
    opening parentheses, and then a blank white space,
  • 11:27
    and then an expression, and then a blank white space,
  • 11:29
    and the closing parentheses.
  • 11:30
    In Drupal, we leave those out.
  • 11:31
    Of course, we have the spaces around the operator here, though.
  • 11:37
    We always put the opening curly brace on the same line
  • 11:39
    as the condition, and the closing curly brace on a line by itself.
  • 11:44
    The exception to this is control structures
  • 11:47
    inside of template files.
  • 11:49
    So inside of a .tpl.php file, we use the expanded if syntax.
  • 11:54
    You can see it here.
  • 11:55
    This makes it a little bit easier to find the closing part of the if
  • 12:00
    statement, when it's mixed in with a whole bunch of HTML.
  • 12:03
    So inside of template files, we use the expanded if structure.
  • 12:07
    Here's some coding standards for calling functions.
  • 12:10
    When you're calling functions in PHP code in Drupal,
  • 12:13
    we always make sure there is no white space between the function
  • 12:16
    name and the parentheses that allow us to call
  • 12:19
    the function in any of its arguments.
  • 12:22
    Arguments are always separated by a comma with a space after the comma,
  • 12:27
    no matter how many arguments there are.
  • 12:29
    So basically, the big thing here is making
  • 12:31
    sure there's a space separating your arguments.
  • 12:34
    And just like with control structures,
  • 12:36
    we make sure there's no extra space inside of the parentheses.
  • 12:39
    Again, a lot of people write PHP code that might be function name,
  • 12:42
    open parentheses, white space, arguments,
  • 12:45
    whitespace, closing parentheses.
  • 12:47
    We don't do that in the Drupal coding standard.
  • 12:50
    When you're declaring functions, it's pretty similar.
  • 12:54
    We make sure there's no space between function name
  • 12:56
    and parentheses.
  • 12:57
    We make sure that arguments are separated by a comma with a space
  • 13:00
    after the comma.
  • 13:02
    Of course, when you're declaring functions,
  • 13:04
    you can also potentially include default values.
  • 13:07
    If a function includes default values,
  • 13:09
    we want those arguments to be at the end of the list.
  • 13:11
    This ensures that it's easier to call the function
  • 13:13
    and pass in all the required arguments
  • 13:15
    and skip the optional ones.
  • 13:18
    And finally, no extra space inside of the parentheses.
  • 13:21
    Arrays-- Drupal has a lot of arrays, so understanding the coding
  • 13:25
    standards for handling arrays is an important one.
  • 13:29
    If the content of the array fits on a line that's
  • 13:31
    less than 80 characters, you can go ahead and put all of those keys
  • 13:34
    and values onto a single line, like the first example here.
  • 13:38
    However, if the content extends to more than 80 characters,
  • 13:43
    you should wrap so that each key value pair is on an individual line
  • 13:46
    of its own-- indented, two spaces, as you
  • 13:49
    can see in the second example.
  • 13:51
    Like with control structures and function calls,
  • 13:53
    we always include a space between elements of an array-- so comma,
  • 13:56
    white space, new element.
  • 13:59
    Finally, make sure you've got spaces around your operator.
  • 14:03
    So when you're declaring a key value pair
  • 14:06
    and you're using the assignment operator here,
  • 14:08
    make sure that you've got a white space on either side.
  • 14:11
    What about quotes-- handling quotes.
  • 14:14
    This one's kind of interesting.
  • 14:15
    There's actually no hard and fast rule
  • 14:17
    that says you have to use single quotes,
  • 14:19
    or you have to use double quotes.
  • 14:21
    But consistency is definitely encouraged.
  • 14:24
    For the most part, I'd recommend that you use single quotes.
  • 14:26
    And you'll see throughout Drupal that's kind of the de facto.
  • 14:29
    People tend to gravitate towards single quotes.
  • 14:32
    However, there are a few cases in which
  • 14:34
    double quotes are definitely required.
  • 14:36
    One of those is variable interpolation.
  • 14:38
    As you can see in the second line here, content equals h2 header,
  • 14:41
    you can use double quotes to allow interpolation.
  • 14:45
    The other case might be inside of a string
  • 14:48
    in the t function, so a translatable string.
  • 14:51
    If you want to do something like have a apostrophe-- so "ain't" here
  • 14:55
    includes an apostrophe-- rather than use single quotes
  • 14:58
    and escape the apostrophe, we use double quotes
  • 15:00
    that surround the string that contains an apostrophe.
  • 15:02
    This makes it easier for translators to handle,
  • 15:04
    because they don't have to worry about escaping the characters
  • 15:07
    in the string that they're translating.
  • 15:09
    Concatenating variables and strings together-- the big thing here
  • 15:13
    is that we always use white space on either side
  • 15:16
    of concatenation operator.
  • 15:18
    So string, space, dot, space, variable.
  • 15:21
    There's a bunch of examples here, always using that white space.
  • 15:25
    Other PHP projects use a pattern that
  • 15:28
    is sort of like string, dot, white space, bar.
  • 15:32
    So there's only a single white space, and not one on either side.
  • 15:34
    But we definitely stick to one white space
  • 15:37
    on either side of the operator.
  • 15:39
    Handling comments-- this one's interesting.
  • 15:42
    So when you're writing comments, especially doc block comments
  • 15:45
    for a function, here's some standard rules to stick to.
  • 15:49
    We always stick to 80 characters.
  • 15:51
    So if your comment, or any line of text in the comment,
  • 15:55
    hits the 80 character mark, you should wrap it to a new line.
  • 16:00
    When you're writing a doc block comment for a function,
  • 16:03
    the first line of the doc block is considered the function summary.
  • 16:06
    And your function summary should always be 80 characters or less.
  • 16:10
    When you're declaring or documenting the parameters for a function,
  • 16:13
    we do so using standard doc block style-- @param, the type
  • 16:18
    of the parameter, so int, the name of the parameter, then a new line
  • 16:24
    indented, and then the comments or documentation of that parameter.
  • 16:30
    We also always document our return values.
  • 16:33
    If you're writing comments in line with your code,
  • 16:36
    also keep in mind that you should wrap those at 80 characters
  • 16:39
    as well.
  • 16:40
    So if you're using inline comment, kind of like the //Magic one you
  • 16:43
    see here, that should be wrapped at 80 characters.
  • 16:46
    One important thing to remember about these doc block comments
  • 16:49
    that we're writing is that doc block comments are used by tools
  • 16:52
    like api.drupal.org and different IDEs
  • 16:54
    like PhpStorm in order to parse that comment,
  • 17:00
    understand what that function does, and provide documentation for it.
  • 17:03
    If we don't follow the format, it's harder for those tools to work.
  • 17:07
    So that's kind of a rough summary of the PHP coding standards for Drupal
  • 17:12
    that really covers all of the basics.
  • 17:14
    Of course, the best way to learn these
  • 17:16
    is to practice them and just make sure
  • 17:18
    that you do it all of the time.
  • 17:20
    When we first start writing PHP though, of course
  • 17:23
    we're going to probably end up violating the coding standards.
  • 17:25
    I mean, I've been doing this for 10-plus years,
  • 17:28
    and I still catch myself violating the coding
  • 17:30
    standards from time to time.
  • 17:32
    There are some helpers that will make it easier for us to detect
  • 17:35
    when our code violates the coding standards and fix those things.
  • 17:38
    Check out the Coder Module.
  • 17:40
    It's got some tools for reviewing your code
  • 17:42
    and pointing out standards violations, as well
  • 17:44
    as the combination of the PHPCS tool and the Coder Sniffer module
  • 17:51
    on drupal.org.
  • 17:52
    This is a set of tools that will allow you to run a command line
  • 17:54
    PHPCS argument, pass in the file that you would like to validate.
  • 17:58
    It'll run a set of linting tools on your file
  • 18:01
    and see, like, yes, it matches the coding standards,
  • 18:03
    or no, there's a violation and here's what it is
  • 18:05
    and where it is you should go ahead and fix it.
  • 18:08
    One of the things that's really cool about PHPCS and the Coder Sniffers
  • 18:12
    is that it doesn't require bootstrapping Drupal in order
  • 18:14
    to run.
  • 18:15
    And as such, it has some pretty cool integration
  • 18:17
    with a lot of different IDEs and editors.
  • 18:19
    I use PhpStorm, for example, and I've
  • 18:21
    got it configured so that if my code violates the coding standard,
  • 18:24
    PhpStorm will actually highlight that line of code
  • 18:27
    and alert me that something's wrong so I can fix it right away.
  • 18:30
    It's all about the details.
  • 18:31
    It's all about the way that our code looks
  • 18:33
    and making it easy for the people that we're sharing that code with
  • 18:36
    to read, and for our future selves to read.
  • 18:38
    So we make sure and leave plenty of comments
  • 18:40
    and to follow the coding standards so that when we come down to it
  • 18:43
    and we need to read it, we can spend time focusing on what the code does
  • 18:48
    and not what it looks like.
  • 18:49
    I encourage you to start playing with the Drupal coding standards
  • 18:52
    and making sure that in your own projects, you're following them.

Drupal Coding Standards

Loading ...

Understanding the Drupal Coding Standards

Loading...

The Drupal community has defined a set of coding standards and best practices that should be adhered to whenever you're writing code for Drupal. These standards provide a set of rules for how your code should be formatted, whether you should use tabs or spaces, some guidelines around naming conventions, and the location of files. These coding standards ensure consistency in code throughout the project, make it easy for developers to move around from one sub-section to another without having to re-learn how to read the code, and most of all help us to spend our time debating the functionality and logic contained in the code and not the semantics of whitespace. You can simply point to the rules and say, "This is what we agreed on."

This tutorial will cover the PHP coding standards for Drupal, as well as provide some information about why coding standards are important and where you can go to learn more about the coding standards. These standards are Drupal version agnostic and the same rules apply to all versions of Drupal. Once you've completed the tutorial you'll probably want to head over to https://www.drupal.org/coding-standards where the official documentation of the coding standards lives. That page should be considered the canonical source for any questions about the Drupal coding standards.

We're not going to cover every little detail, but we'll make sure and go over the things you're likely to encounter no a daily basis when writing code. By the end of this tutorial you should be ready to start applying the Drupal PHP coding standards to your own custom PHP code and to all your contributions.

Downloads: 
Log in or sign up to download companion files.
Additional resources: 

Average review

0
No votes yet

Reviews