Skip to content

Style guides for Google-originated open-source projects

Notifications You must be signed in to change notification settings

ggould-tri/styleguide

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Drake Style Guide

This repository is a fork of Google's style guide. Drake's C++ style is a small deviation from Google's, and approximately tracks Google's latest style guidance at a small delay.

The README for Google's style guide follows after some Drake-specific notes below.

Maintenance Philosophy

This style guide should be updated in two cases:

  • The agreement of the Drake platform reviewers on a change to our style rules.

  • A change from the upstream Google style guide which has been reviewed (and altered if necessary) by the Drake platform reviewers.

Both sorts of updates should use ordinary Reviewable review for the platform reviewer discussion.

When making a change, annotate an html tag surrounding the new material with class="drake". This makes it easy for readers to see Drake-relevant changes and for maintainers to understand our diffs. Annotate Google material that is superseded by Drake changes but is still useful for reference with class="nondrake".

When making a change, avoid changing whitespace or indentation unnecessarily. Conflict resolution is difficult in prose text, and conflicts that are just paragraph reflows make future maintainers cry.

Making New Changes

Branch, update, and PR as you would any other Drake change.

Pulling Upstream Changes

A Drake style guide maintainer should keep a local clone of this repository. This should be set up in the usual manner, but with remotes to both Google and Drake as you will want to be able to rebase from either one:

  • Fork "styleguide" into your account, this is where all your branches will be

  • Check out your own fork

    • Go to forked repository https://github.com/**USERNAME**/styleguide and press the green "Clone or download" button, then select "ssh" and copy ssh URL

    • Clone it on your local machine:

         git clone URL_YOU_JUST_COPIED
         cd styleguide
      
  • Add a "drake" remote for the Drake styleguide and make it the default upstream. Note that for compatibility with Google, we use the branch gh-pages as our master:

     git remote add drake [email protected]:RobotLocomotion/styleguide.git
     git remote set-url --push drake no_push
     git branch --set-upstream-to drake/gh-pages
    
  • Add a "google" remote for the Drake styleguide:

     git remote add google [email protected]:google/styleguide.git
     git remote set-url --push google no_push
    

Now that you have a repository and remotes set up, you want to be up-to-date with Drake and then pull Google's changes:

git co gh-pages
git pull --ff-only
git co -b **NEW_BRANCH_NAME**
git pull --rebase google gh-pages
**RESOLVE CONFLICTS**
git push --set-upstream origin **NEW_BRANCH_NAME**
**ORDINARY PR PROCESS**

There is a high likelihood that this rebase will have conflicts. These conflicts represent google changes to or near Drake-specific style rules and should be considered carefully rather than accepted or rejected blindly.

When you have resolved the rebase you should commit, push, and PR in the usual manner. In creating the PR, double-check that you are PR'ing against RobotLocomotion/styleguide, not google/styleguide.

You should add all of the platform reviewers to the resulting PR.

--

Google Style Guides

Every major open-source project has its own style guide: a set of conventions (sometimes arbitrary) about how to write code for that project. It is much easier to understand a large codebase when all the code in it is in a consistent style.

“Style” covers a lot of ground, from “use camelCase for variable names” to “never use global variables” to “never use exceptions.” This project (google/styleguide) links to the style guidelines we use for Google code. If you are modifying a project that originated at Google, you may be pointed to this page to see the style guides that apply to that project.

This project holds the C++ Style Guide, Objective-C Style Guide, Java Style Guide, Python Style Guide, R Style Guide, Shell Style Guide, HTML/CSS Style Guide, JavaScript Style Guide, AngularJS Style Guide, Common Lisp Style Guide, and Vimscript Style Guide. This project also contains cpplint, a tool to assist with style guide compliance, and google-c-style.el, an Emacs settings file for Google style.

If your project requires that you create a new XML document format, the XML Document Format Style Guide may be helpful. In addition to actual style rules, it also contains advice on designing your own vs. adapting an existing format, on XML instance document formatting, and on elements vs. attributes.

The style guides in this project are licensed under the CC-By 3.0 License, which encourages you to share these documents. See https://creativecommons.org/licenses/by/3.0/ for more details.

The following Google style guides live outside of this project: Go Code Review Comments and Effective Dart.

Creative Commons License

About

Style guides for Google-originated open-source projects

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • HTML 65.4%
  • Python 26.8%
  • XSLT 4.4%
  • CSS 1.4%
  • JavaScript 1.2%
  • Emacs Lisp 0.7%
  • Other 0.1%