<commit_before>+++
title = "Samples Style Guide"
linkTitle = "Samples Style Guide"
 
+++
 
 
# Samples Style Guide
 
## Introduction
 
This document serves as a definition of our samples standards for both
standalone snippets and sample applications. It is intended to help encourage
consistency and best practices when authoring code intended to teach others.
 
Even if not specifically mentioned in the guide, all samples should make
best-efforts to achieve the following goals wherever possible:
 
* **Copy-paste-runnable** - Users should be able to copy, paste, and run the
code into their environment with as few changes as possible. Samples should be
easy as possible for a user to run.
 
* **Teach through code** - Samples should teach users both how and _why_
specific best practices should be implemented and performed when interacting
with our services.
 
* **Idiomatic** - Samples should encourage idiomatic and best practices specific
to language, framework, or service.

## Structure

### Region tags
 
Each code snippet should have a region tag to define which parts of the snippet
are displayed from the documentation. Each region tag should be:
* Globally unique
* Consistent across the same snippets in different languages
* Begins with the product's region tag prefix
* In snake case

Region tags should show as much of the sample as possible, so that a user can
easily copy and pase the sample into their own environment to run it. 

### Imports
 
Samples should include any imports used in the sample.
 
This is easiest to enforce/detect when the samples are in their own file, so
samples should be structured as such unless their is a compelling reason not to.
 
{{< tabpane langEqualsHeader=true >}}
 {{< tab header="Java" >}}
   // Region tags should start after the package, but before imports.
   // [START product_example]
   import com.example.resource;
 
   public class exampleSnippet {
   // Snippet methods ...
   }
   // [END product_example]
 {{< /tab >}}
 {{< tab header="Python" >}}
  # [START product_example]
  import com.example.resource
 
  def example_snippet():
       # Snippet Content ...
 
  # [END product_example]
 {{< /tab >}}
{{< /tabpane >}}


## Code <commit_msg>feat: add section about sample description (#5)<commit_after>+++
title = "Samples Style Guide"
linkTitle = "Samples Style Guide"
 
+++
 
 
# Samples Style Guide
 
## Introduction
 
This document serves as a definition of our samples standards for both
standalone snippets and sample applications. It is intended to help encourage
consistency and best practices when authoring code intended to teach others.
 
Even if not specifically mentioned in the guide, all samples should make
best-efforts to achieve the following goals wherever possible:
 
* **Copy-paste-runnable** - Users should be able to copy, paste, and run the
code into their environment with as few changes as possible. Samples should be
easy as possible for a user to run.
 
* **Teach through code** - Samples should teach users both how and _why_
specific best practices should be implemented and performed when interacting
with our services.
 
* **Idiomatic** - Samples should encourage idiomatic and best practices specific
to language, framework, or service.

## Structure

### Region tags
 
Each code snippet should have a region tag to define which parts of the snippet
are displayed from the documentation. Each region tag should be:
* Globally unique
* Consistent across the same snippets in different languages
* Begins with the product's region tag prefix
* In snake case

Region tags should show as much of the sample as possible, so that a user can
easily copy and pase the sample into their own environment to run it. 

### Imports
 
Samples should include any imports used in the sample.
 
This is easiest to enforce/detect when the samples are in their own file, so
samples should be structured as such unless their is a compelling reason not to.
 
{{< tabpane langEqualsHeader=true >}}
 {{< tab header="Java" >}}
   // Region tags should start after the package, but before imports.
   // [START product_example]
   import com.example.resource;
 
   public class exampleSnippet {
   // Snippet methods ...
   }
   // [END product_example]
 {{< /tab >}}
 {{< tab header="Python" >}}
  # [START product_example]
  import com.example.resource
 
  def example_snippet():
       # Snippet Content ...
 
  # [END product_example]
 {{< /tab >}}
{{< /tabpane >}}

### Sample description
 
Each code snippet file should have a top-level comment that succinctly describes
what the snippet does, including any setup (such as resources) required to make
the sample work:
 
{{< tabpane langEqualsHeader=true >}}
 {{< tab header="Java" >}}
   /**
   * Moves a persistent disk from one zone to another.
   *
   * See https://cloud.google.com/compute/docs/quickstart-client-libraries before running the code snippet.
   */
 {{< /tab >}}
{{< /tabpane >}}


## Code 
{'fraction_non_alphanumeric': 0.07606716568885293, 'fraction_numerical': 0.00020230629172567267, 'mean_word_length': 3.8613569321533925, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 19, 'https://': 1, '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': '1315404', 'n_tokens_mistral': 1336, 'n_tokens_neox': 1240, 'n_words': 644}