<commit_before>---
layout: documentation
title: BUILD Style Guide
---

# BUILD Style Guide


In `BUILD` files, we take the same approach as in Go: We let the machine take care
of most formatting issues.
[Buildifier](https://github.com/bazelbuild/buildifier) is a tool that parses and
emits the source code in a standard style. Every `BUILD` file is therefore
formatted in the same automated way, which makes formatting a non-issue during
code reviews. It also makes it easier for tools to understand, edit, and
generate `BUILD` files.

`BUILD` file formatting must match the output of `buildifier`.


## Contents

- [Formatting example](#formatting-example)
- [File structure](#file-structure)
- [References to targets in the current package](#references-to-targets-in-the-current-package)
- [Target naming](#target-naming)
- [Visibility](#visibility)
- [Dependencies](#dependencies)
- [Globs](#globs)
- [Other conventions](#other-conventions)
- [Differences with Python style guide](#differences-with-python-style-guide)

## Formatting example

```python
package(default_visibility = ["//visibility:public"])

py_test(
    name = "foo_test",
    srcs = glob(["*.py"]),
    data = [
        "//data/production/foo:startfoo",
        "//foo",
        "//third_party/java/jdk:jdk-k8",
    ],
    flaky = True,
    deps = [
        ":check_bar_lib",
        ":foo_data_check",
        ":pick_foo_port",
        "//pyglib",
        "//testing/pybase",
    ],
)
```

## File structure

We recommend to use the following order (every element is optional):

  * Package description (a comment)

  * All `load()` statements

  * The `package()` function.

  * Calls to rules and macros

Buildifier makes a distinction between a standalone comment and a comment
attached to an element. If a comment is not attached to a specific element, use
an empty line after it. The distinction is important when doing automated
changes (e.g. to decide if we keep or remove a comment when we delete a rule).

```python
# Standalone comment (e.g. to make a section in a file)

# Comment for the cc_library below
cc_library(name = "cc")
```
<commit_msg>Make the formatting example more like the written text by adding an initial description.<commit_after>---
layout: documentation
title: BUILD Style Guide
---

# BUILD Style Guide


In `BUILD` files, we take the same approach as in Go: We let the machine take care
of most formatting issues.
[Buildifier](https://github.com/bazelbuild/buildifier) is a tool that parses and
emits the source code in a standard style. Every `BUILD` file is therefore
formatted in the same automated way, which makes formatting a non-issue during
code reviews. It also makes it easier for tools to understand, edit, and
generate `BUILD` files.

`BUILD` file formatting must match the output of `buildifier`.


## Contents

-   [Formatting example](#formatting-example)
-   [File structure](#file-structure)
-   [References to targets in the current package](#references-to-targets-in-the-current-package)
-   [Target naming](#target-naming)
-   [Visibility](#visibility)
-   [Dependencies](#dependencies)
-   [Globs](#globs)
-   [Other conventions](#other-conventions)
-   [Differences with Python style guide](#differences-with-python-style-guide)

## Formatting example

```python
# Test code implmenting the Foo controller.
package(default_visibility = ["//visibility:public"])

py_test(
    name = "foo_test",
    srcs = glob(["*.py"]),
    data = [
        "//data/production/foo:startfoo",
        "//foo",
        "//third_party/java/jdk:jdk-k8",
    ],
    flaky = True,
    deps = [
        ":check_bar_lib",
        ":foo_data_check",
        ":pick_foo_port",
        "//pyglib",
        "//testing/pybase",
    ],
)
```

## File structure

We recommend to use the following order (every element is optional):

*   Package description (a comment)

*   All `load()` statements

*   The `package()` function.

*   Calls to rules and macros

Buildifier makes a distinction between a standalone comment and a comment
attached to an element. If a comment is not attached to a specific element, use
an empty line after it. The distinction is important when doing automated
changes (e.g. to decide if we keep or remove a comment when we delete a rule).

```python
# Standalone comment (e.g. to make a section in a file)

# Comment for the cc_library below
cc_library(name = "cc")
```

{'fraction_non_alphanumeric': 0.1130830489192264, 'fraction_numerical': 0.0004550625711035267, 'mean_word_length': 3.632244467860906, 'pattern_counts': {'":': 6, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2469110', 'n_tokens_mistral': 1328, 'n_tokens_neox': 1249, 'n_words': 487}