style_guide.md

How to Write DevPlatform Style Guides

Author: Shailen Tuli
Reviewers: Trevor Johns, Kathy Walrath

This is an early draft. Please give us your feedback.

Introduction

This document provides guidelines for creating style guides for DevPlatform-created code, such as sample code (including code excerpts shown in docs), libraries, and apps.

Style guides help in the following ways:

• They bring consistency to code that DevPlatform produces.
• They save developers from having to invest time grappling with coding style issues.
• They reduce friction in the code review process.

All DevPlatform style guides are public, so that external developers know what to expect. Having public style guides is especially important for projects that accept contributions.

General considerations

Before you write a style guide, look for an existing public style guide that you can use. Many languages have official style guides (PEP8 for Python, for example); others have unofficial guides that are widely accepted by the community.

Where possible, use existing style guides and add a list of whatever modifications are necessary for samples, libraries, and apps.

Dealing with existing Google style guides

Prefer community standards over Google’s style guides, when they are in conflict. Google’s existing style guides are optimized for consistency with our internal codebase; the DevPlatform team is more concerned with general readability and code portability to non-Google projects. Feel free to use existing public guides from Google, and then recommend specific modifications.

Rules for all style guides

Whether you build on an existing style guide or write one from scratch, follow these guidelines.

Be clear about the scope

If a guideline applies only to samples, then say so. For example, you might specify when and how a sample can omit exception handling.

Recommend tools

Find and recommend tools that can help developers produce code that conforms to your style guide. For example, you might recommend lint tools such as pylint and JSHint. Formatting tools like gofmt can help, too.

Minimize ambiguity

Avoid TMTOWTDI ("Tim Towdy" / "There's more than one way to do it") coding practices. Recommend a single way to do things where possible. Our samples do not need to use every feature of every language. They do need to be stylistically consistent.

Specify what the code can depend on

Specify when to use libraries and frameworks, and when to write ‘pure’ samples. Specify dependency versions to prevent compatibility issues.

Recommend a testing framework

Specify a testing framework in your guide. Pick a framework that is widely used, and which is easy for Dev Platform members to quickly learn to use (a JUnit based framework, for example).

Provide exception handling guidelines

Sample code is different from other code in that it primarily exists to demonstrate the use of a specific API or feature. For this reason, the sample author may want to simplify the code to the bare essentials. You can help the sample author by including in your guide recommendations for when it is acceptable to leave out exception handling.

Customizing an existing style guide

Here are some examples of how you might customize an existing style guide:

• Simplifying directory structure: Your code uses a framework that recommends a specific directory structure. However, small samples can be more readable if they have fewer files and directories. Your style guide should help developers figure out a consistent way to consolidate code.

• Removing complexity: You're building on a style guide that places no restrictions on using anonymous functions as the value of callback parameters. For better readability, though, you think it is better to have named functions. Consider suggesting modifications to the style guide to restrict the use of features that lead to readability problems.

Referencing other Dev Platform style guides

Don't duplicated content in another Dev Platform style guide. Instead, layer your style guide on top of existing guides. For example:

• a polymer.js or node.js guide builds on top of the JavaScript guide.

• an Android games guide builds on top of the Android guide, which builds on top of the Java guide.

Creating a style guide from scratch

** Do this only if there is no existing guide that you can use.**

Style guides are language specific and sometimes framework specific, but here is a list of topics that are likely to show up in most style guides. Address these in your guide:

Code layout

• indentation
• tabs or spaces?
• maximum line length
• continued line indentation
• blank lines
• block style (for example, where to put the { and }, and using {} vs. do ... end in Ruby)

Whitespace in expressions and statements

• inside (), {}, [], etc.
• around comma, colon, and semicolon
• around operators

Comments

• when to use block comments
• when to use inline comments
• how to write doc comments

Naming conventions

• allowed/disallowed characters in names

• use cases for the following:

  • lowercase
  • UPPERCASE
  • lowercase_with_underscores
  • UPPERCASE_WITH_UNDERSCORES
  • CapitalizedWords
  • camelCase
  • leading and trailing _ (single underscore)
  • leading and trailing __ (double underscore)

• naming conventions for the following:

  • classes
  • exceptions
  • global variables
  • functions
  • function and method arguments
  • method names and instance variables
  • constants
  • filenames
  • module/library names

Sample directory structure

• inline code vs. separate file
• order of includes/imports
• include/import DOs and DON’Ts

Scoping

• use of namespaces
• nested classes and functions
• static members
• policy on use (or disuse) of globals
• local variables

Code organization

• when to use which kind of constructor
• multiple inheritance DOs and DON’Ts
• mixin DOs and DON’Ts
• operator overloading
• function overloading
• default arguments
• use of const, final, etc.
• when to use single, double, or triple quotes for strings

Using Markdown

Write your style guide using Github flavored Markdown. You can preview the rendered HTML by creating a Gist on Github and giving it a .markdown or .md extension.