Patterns and conventions

Coding patterns the codebase enforces, and how to follow them in new code.

Style guides

• C++: Google C++ Style Guide. Format with clang-format (configured in .clang-format).
• Python: PEP 8 with Google flavor (4-space indent, no * imports). Lint with pylint configured by tensorflow/tools/ci_build/pylintrc (top-level symlink .pylintrc).
• Bazel: buildifier (run before sending PRs).
• Markdown / docs: lower-case headings in some sub-projects, but match the surrounding file's style.

CONTRIBUTING.md has links to the official Google style guides and several language-specific notes.

Naming

• C++ files: snake_case.{h,cc}. CUDA files: *.cu.cc.
• C++ types: CamelCase for classes, kCamelCase for constants.
• Python: snake_case for modules, functions, vars; CamelCase for classes; UPPER_SNAKE for module-level constants.
• Op kernels: file named after the op family (e.g. matmul_op.cc, cwise_op_add.cc); the op class is MatMulOp.
• Test files end in _test.cc or _test.py; mock/test helpers in *_test_util.{cc,h,py}.

Error handling

C++

• Returning errors uses tensorflow::Status (now an alias for absl::Status). The macros in tensorflow/core/platform/errors.h (TF_RETURN_IF_ERROR, TF_ASSIGN_OR_RETURN) are the canonical way to propagate them.
• Op kernels signal errors by setting OpKernelContext::SetStatus(...) or via the OP_REQUIRES_OK(ctx, ...) macro. Never throw exceptions.
• Long-lived async operations use Status callbacks; sync APIs return Status directly.

TF_RETURN_IF_ERROR(ReadFromFile(filename, &out));
OP_REQUIRES(ctx, input.dims() == 2,
            errors::InvalidArgument("expected rank-2 input"));

Python

• Public APIs raise tf.errors.* from tensorflow/python/framework/errors_impl.py (InvalidArgumentError, OutOfRangeError, ResourceExhaustedError). These wrap C++ statuses on the way out of pybind11.
• For internal Python logic, ValueError, TypeError, RuntimeError are standard.
• Don't raise inside @tf.function-traced graphs; use tf.debugging.assert_* instead so the assertion becomes a graph node.

Op + kernel registration

A new op normally needs both:

1. An OpDef under tensorflow/core/ops/. Registered with REGISTER_OP("Foo").Input(...).Output(...).SetShapeFn(...).
2. A kernel under tensorflow/core/kernels/. Registered with REGISTER_KERNEL_BUILDER(Name("Foo").Device(DEVICE_CPU), FooOp).

If you change inputs/outputs/attrs of an existing op, you usually need a new op name and a v2 kernel — TF's API stability guarantees forbid breaking existing ops. See systems/kernels-and-ops.

Generated code

A lot of Python is generated:

• Python wrappers for ops (e.g., tensorflow/python/ops/gen_math_ops.py) are produced from OpDef registrations by Bazel rules in tensorflow.bzl.
• API export markers come from @tf_export("foo.bar") decorators (tensorflow/python/util/tf_export.py). The api_template*.py files at the repo root are the templates the docs build uses to fill tensorflow/_api/....
• Don't hand-edit gen_* files — change the upstream REGISTER_OP or template instead.

Backwards compatibility

TensorFlow has explicit API stability guarantees (documented at tensorflow.org under "Versioning"). Implementation in tensorflow/python/util/deprecation.py, with decorators like @deprecated, @deprecated_args, @deprecated_endpoints. When you see one of those decorators, it's making a contract: the function will keep working but emit a warning until at least the next major version.

Cross-cutting patterns

• Trackable / tf.train.Checkpoint — to make a Python class checkpointable, subclass tensorflow/python/trackable/base.py and expose dependencies through _track_trackable or _checkpoint_dependencies.
• tf.Module — the lightweight base class for all tf.keras.layers.Layer, tf.keras.Model, and most user-facing Python classes (tensorflow/python/module/module.py).
• tf_export — the public API surface is defined by @tf_export decorators. Anything not exported is private.
• Resource variables — almost all variables are ResourceVariable (tensorflow/python/ops/resource_variable_ops.py); the older RefVariable is rarely used.

Related

• tooling — how the generators run.
• systems/kernels-and-ops — kernel patterns in detail.