The Benefits of Using Style Guides When Writing Code

Share this post

Working as part of a group of developers can have its own special complications beyond the usual programming hurdles. Like travelers on a journey, two developers might take wildly different paths to the same destination. One might declare a variable as myVariable, while the other might call it my_variable. One might prefer an empty line between function declarations, and the other might not.

These may sound like trifling details, but when working on a large project these minor variances can quickly become major inconsistencies. Consider one simple PHP function written by two different developers:

Style Guide

As you will notice, there are numerous differences in code styles here. Some approaches are more efficient, while some are a matter of taste. For example, Programmer #1 begins his function with a block-style comment, while Programmer #2 prefers a simpler inline double-slash. Programmer #1 uses a two-space indent, and #2 appears to be using his tab key.

Both examples are perfectly valid and probably fine for small projects, but try to imagine these inconsistencies spread across hundreds of files and thousands of lines of code. If a team of developers is not working under a style guide, shared resources may become muddled as individuals struggle to remember the variable or file they are supposed to reference.

Am I supposed to include className.php or class_name.php?

Is the site session called site_session or siteSession?

Additionally, code quickly becomes confusing and hard to interpret, particularly in languages like PHP or JavaScript which lack strict data typing. Can you tell, at a glance, if $myVariable is supposed to be a constant? You might be able to, if everyone in your group agreed to write constant variables in capital letters: $MY_VARIABLE. Is it a number, a string, or an array of values? Maybe it’s a function argument, or a global.

As you can see, proper naming conventions can greatly improve group efficiency. Different companies or groups will have specific established standards, but what is most important is consistency. Decide on a set of rules that each developer will abide by, and enforce these standards during your normal code review process.

If you aren’t sure where to start, here are a few general styling rules to consider:

  • Do you use the tab character or spaces for indenting? How many spaces deep is each line?
  • How do you handle comments? Is there a special way to explain functions?
  • Spacing between lists of variables.
  • Naming conventions for variables, functions, classes, and files.

Style guides are also going to be different between languages. If you do not want to make your own, you might consider using some established guides developed (and used) by major players. Here are a few that are commonly used:

  1. Google styleguides
  2. Microsoft C#
  3. Oracle Java
  4. Pear PHP coding standards
  5. GitHub StyleGuide

Finally, there are a handful of software tools that can automate the detection of common style violations. A good one for general web development is PHPCodeSniffer. Lint is also a very old syntax checker which has been adapted for a variety of languages, and is even used in some websites which offer online code verification. Take a look.

Standardized coding is an important part of professional development and should be implemented as early as possible to avoid later confusion. When developing a style guide, try to involve your entire team. Remember that standards cannot be enforced unless everyone agrees on what that standard is.

Does your team have a style guide? Tell us your experiences.

Your Dilemma: Which Agency Should You Choose?

The answer to this one is simple: Pick CommonPlaces

Our goal is not to simply win a bid, it’s to act as a partner for a company and help it succeed. Providing that level of service requires experience, trust, and delivering final products.

You can see our about page to understand our experience. We have a cornucopia of experience. 

The seed of trust is planted during our initial interactions. We are honest in our interactions and that will come through in our communications.

And we deliver results. The biggest proponents of CommonPlaces can be found in our current and past clients. Our team will be happy to connect you.

Related Posts

The Dilemma of Estimates

The Dilemma of Estimates

Estimates serve as the cornerstone of any website project, providing clients with a roadmap for budgeting, planning, and expectation management. They offer a glimpse into the intricate tapestry of tasks, timelines, and resources needed to bring a website to life.

Config Sync Overview

Config Sync Overview

When Drupal 8 was released, it came with Configuration Syncing functionality. This has been a staple ever since for Drupal 9, Drupal 10, and beyond. Configuration Syncing was a game changer and one of my favorite features in Drupal Core.The days before config sync...