Skip to content

Latest commit

 

History

History
324 lines (242 loc) · 13.5 KB

code-examples.mdx

File metadata and controls

324 lines (242 loc) · 13.5 KB
Raw
title tags redirects
Code references
Basic style guide
Style guide quick reference
/docs/new-relic-only/basic-style-guide/writing-guidelines/code-examples
/docs/new-relic-only/tech-writer-style-guide/processes-procedures/formatting-terminal-commands
/docs/style-guide/writing-guidelines/formatting-terminal-commands/
/docs/style-guide/quick-reference/code-examples/
/docs/code-formatting-guidelines
/docs/new-relic-only/basic-style-guide/writing-guidelines/code-formatting-guidelines
/docs/style-guide/writing-guidelines/code-formatting-guidelines-var-mark
/docs/style-guide/formatting/code-formatting-guidelines-var-mark
/docs/style-guide/formatting/code-examples/

import styleguideSyntaxHighlightingExampleCode from 'images/style-guide_screenshot-crop_syntax-highlighting-example-code.webp'

import apisDataCodeHighlight from 'images/apis-and-data_screenshot-crop_code-highlight.webp'

We use a variety of formatting to highlight code or other technical language.

When to use code formatting [#when_code]

The following table provides some examples of when you should use backticks to highlight code or other strings:

  <th>
    Why use code?
  </th>

  <th>
    Example
  </th>
</tr>

  <td>
    Using code helps paths and file names stand out, and ensures clarity about the exact file name.
  </td>

  <td>
    The agent looks for `newrelic.config` in the `%ALLUSERSPROFILE%\New Relic\.NET Agent` directory.
  </td>
</tr>

<tr>
  <td>
    NRDB event names and attributes
  </td>

  <td>
    Many attribute names (such as `duration`) look like ordinary English words. Formatting them as code helps clarify that we're talking about a specific data point.
  </td>

  <td>
    To analyze APM errors, use the `TransactionError` event.
  </td>
</tr>

<tr>
  <td>
    Method names
  </td>

  <td>
    Using code formatting for method names is standard practice, and helps disambiguate the method name from surrounding text. Include `()` after the name.
  </td>

  <td>
    To initialize the APM agent, use `startAgent()`.
  </td>
</tr>

<tr>
  <td>
    URLs you don't intend to be clicked
  </td>

  <td>
    Using code formatting hints to the user that they may need to customize or tweak the URL to ensure it works for them.
  </td>

  <td>
    In your web browser, navigate to the minion **Overview** page at `http://MINION_IP_ADDRESS`.
  </td>
</tr>

<tr>
  <td>
    Command line utility names
  </td>

  <td>
    If you think a reader or translator might confuse a command with a general English word, use code.

    * `curl`: Sends http requests via a terminal session–not to be confused with the curls you do with weights at the gym.
    * `cat`: Lists the first ten lines of a file–not a feline pet who ignores you.
    * `date`: Displays the day, year, and time–not an outing that couples take.
    * `tail`: Displays the last ten lines of a file–not the appendage on various mammals.
    * `which`: Show the location of a program executable–not the pronoun.
  </td>

  <td>
    To install the utility, use `apt`.
  </td>
</tr>
For this...
File paths and file names

Inline code formatting [#inline-code]

To format inline code (like maxSampleTimes or TransactionError), surround the text with backtick ` characters.

Multi-line code blocks [#code-block]

To format one or more lines of code, insert three backticks ( ``` ) above and below your code. This essentially acts like the HTML <pre> tag.

When you sandwich your code snippets between three backticks, you need to consider both the code indentation and the syntax highlighting.

Strict indentation [#strict]

As a technial writer you'll be given code snippets from a variety of languages. To make it easier for your readers to understand code snippets, make sure that lines are indented and grouped in a helpful way.

Some programming and markup languages require specific indentation (for example, Python and YAML). Check with your subject matter expert if you are unsure about whether the snippet you've been given needs to have specific indentation in order to work. You can always run the snippet through an online code prettifier if it gets jumbled when you transfer it from another editing tool.

Here's an example of some Python code that will break if you change the indentation:

import newrelic.agent
newrelic.agent.initialize('newrelic.ini') #This is required!

def greet(name):
    """
    This function says hello to
    the person who is passed in as
    a parameter
    """
    print("Hello, " + name + " and the world!")


def execute_task(application, task_name):
    with newrelic.agent.BackgroundTask(application, name=task_name, group='Task'):
        greet("Robert")

application = newrelic.agent.register_application(timeout=10)
execute_task(application, "bar")
newrelic.agent.shutdown_agent(timeout=10)

Non-strict indentation [#casual]

For free-form languages, which are casual about indentation, we recommend that you look for similar examples and follow those patterns. Java and SQL are examples of free-form languages.

How to format NRQL [#NRQL]

NRQL is a free-form query language, which means that it doesn't have strict indentation rules. We recommend you follow some simple guidelines to make it easier to read. Our suggestions are loosely based on some SQL formatting guidelines.

You can use your discretion to decide if these guidlines apply to your snippet:

  • Capitalize clause keywords such as FROM, SELECT, FACET, WHERE, AND, OR, AS, SINCE, ORDER BY, TIMESERIES, EXTRAPOLATE, and AUTO.
  • Don't capitalize functions, such as min(), max(), average(), percentile(), sum(), and stddev(), since query builder doesn't automatically capitalize these names. If you're not sure if a keyword is a function, see NRQL reference.
  • The first line should start with a FROM clause, even though queries run fine when you start with SELECT.
  • Left-justify clause keywords except in the following cases:
    • If a clause keyword is closely tied to a preceding keyword (for example, AGO is closely tied to SINCE), it belongs on the same line.
    • If a clause keyword doesn't have any modifiers (it stands alone), you can tack it at the end of a line that already has keywords (for example, TIMESERIES, AUTO, and EXTRAPOLATE).
    FROM Transaction
SELECT count(*)
WHERE appName='interestingApplication'
SINCE 60 minutes AGO EXTRAPOLATE
  • For keywords inside of parentheses that span multiple lines, indent them two spaces. For example, the WHERE keyword is indented two spaces like this: 
    FROM PageView
SELECT count(*)
FACET CASES
(
  WHERE duration < 1,
  WHERE duration > 1 and duration < 10,
  WHERE duration > 10
)

Syntax highlighting [#syntax-highlighting]

In addition to checking the indentation and grouping of code snippet lines, we recommend that you add language color coding to make it easier to read. You can add color coding for a variety of programming languages by adding the name of the language immediately following the first three backticks of your snippet. See the collapsers below for how to insert color coding and how to know if your language is supported.

To add syntax highlighting to a code block, insert the language name on the same line as the first three backtacks. Here's an example using some Java code: 
<img
  title="Screenshot showing how to format a Java code block"
  alt="Screenshot showing how to format a Java code block"
  src={styleguideSyntaxHighlightingExampleCode}
/>

This is what the formatting looks like when it's published:

```java
public class SampleTester {

    private String configName;
    private Map<String, Long> maxSampleTimes;

    public SampleTester(String pConfigName) {
        configName = pConfigName;
        maxSampleTimes = new HashMap<>();
    }
```

<Collapser id="add-syntax-highlighting" title="Is syntax highlighting supported for your language?"

If you're not sure if our site will format the code snippets for your particular language, do the following:

1. See if your language is included in the [default list](https://github.com/newrelic/gatsby-theme-newrelic/blob/develop/packages/gatsby-theme-newrelic/gatsby-node.js#L232).

2. If you don't see the language you want to format in the default list, check if it is included in [`gatsby-config.js`](https://github.com/newrelic/docs-website/blob/develop/gatsby-config.js) (look under `prism:`). This file lists all the languages we've added beyond the default list.

3. If you still can't find your language, you can make a PR to add it to `gatsby-config.js`. Before you submit a PR, make sure this language is listed in the [Prism site](https://prismjs.com/#supported-languages).

Highlighting lines of code [#highlight-code]

To highlight entire lines of code in a code block, you can use lineHighlight= to indicate the specific lines you want highlighted. You do this in the same place where you note the syntax. Here's an example of a code block with the first and third through fifth lines highlighted:

const coolThing = {
  key: 'HI',
  tada: 'hello'
}
// this is an important object
// other notes...

Here's what the underlying code looks like for this:

Screenshot of code highlighting format

Note that this requires the simultaneous use of syntax highlighting: you must indicate a language if you want to highlight lines.

Placeholders for customer-specific variables [#value-placeholders]

Sometimes we want to use placeholders for variables whose value will depend on the customer or the situation. For example, you might need to use YOUR_ACCOUNT_ID to indicate a placeholder where the customer is meant to input their New Relic account ID.

Some requirements and tips on crafting customer-specific value placeholders:

  • Use all caps and underscores _ to separate words (also known as SCREAMING_SNAKE_CASE).
  • Don't use other elements, like < or >, or $, unless SMEs make a compelling case for why other elements are needed for a specific language or situation.
  • Address the reader directly using YOUR. For example, use YOUR_ACCOUNT_ID and not ACCOUNT_ID.
  • If you think it may be unclear if a component is something of ours or a third party's, you can add NEW_RELIC to the placeholder. For example, when writing about connecting AWS to New Relic, you may want to specific that an account is ours and not AWS's, like this: YOUR_NEW_RELIC_ACCOUNT_ID.
  • Don't combine them with other punctuation to indicate variables (such as wrapping the text in angle brackets or curly braces).
Below are some general style recommendations for formatting user-specific values: 
* Account IDs and other IDs/#s: `YOUR_ACCOUNT_ID`, `YOUR_USER_KEY`, etc. **This should be the general style used.**
* URLs: [example.com](https://example.com).
* Paths: `PATH/TO/SOMETHING.exe` or maybe `PATH_TO_FILE`.
* Emails: [datanerd@example.com](mailto:datanerd@example.com) or `YOUR_EMAIL_ADDRESS`.
* Bash variables for REST API code: Some placeholders on the docs site have the form $&#x7B;API_KEY}. This is a format used for variables in bash scripts, where users assign values to specific variable names and then call those variables later in the script by using the $VARIABLE_NAME. For more info, see this [explanation of bash variables](http://tldp.org/HOWTO/Bash-Prog-Intro-HOWTO-5.html). This is just to note that this is used in some places, but we should not use this format going forward.

When not to use placeholders [#placeholders]

Placeholders are primarily used for when there is a procedure to be done, like a customer who will be running some code. If there's not a procedure involved and a code snippet is being used to demonstrate what something looks like or should look like, you should not use placeholders. Here are some examples of where you should not use placeholders:

  • Example code or files: if you're showing an example config file or another example that isn't directly procedure-related, use example values and not placeholders.
  • API call responses: if you're including the response of an API call that is meant to show what the response will look like and isn't procedure-related, don't use placeholders.

API Keys

If an API key needs to be referenced as an example in a code block or config, we will need to use placeholder text with asterisks instead of zeros.

Example:

...
-e NEW_RELIC_API_KEY=********************************FFFFNRAL \
...

or

...
NEW_RELIC_LICENSE_KEY=****************************************
...