diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/css/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/css/index.md index 53bc08ae861ed10..cb0f139747bb611 100644 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/css/index.md +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/css/index.md @@ -1,5 +1,5 @@ --- -title: Guidelines for styling CSS code examples +title: Guidelines for writing CSS code examples slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS page-type: mdn-writing-guide --- @@ -10,6 +10,14 @@ The following guidelines cover how to write CSS example code for MDN Web Docs. ## General guidelines for CSS code examples +### Choosing a format + +Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. + +On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/en/index.html). + +Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. + ### Plan your CSS Before diving in and writing huge chunks of CSS, plan your styles carefully. What general styles are going to be needed, what different layouts do you need to create, what specific overrides need to be created, and are they reusable? Above all, you need to try to **avoid too much overriding**. If you keep finding yourself writing styles and then cancelling them again a few rules down, you probably need to rethink your strategy. @@ -26,7 +34,7 @@ Don't use preprocessor syntax, such as [Sass](https://sass-lang.com/), [Less](ht In the same spirit as the previous guideline, don't write example codes on MDN Web Docs using a specific CSS methodology such as [BEM](http://getbem.com/naming/) or [SMACSS](http://smacss.com/). Even though they are valid CSS syntax, the naming conventions can be confusing to people not familiar with those methodologies. -### Don't use resets +### Don't use resets For maximum control over CSS across platforms, a lot of people used to use CSS resets to remove every style, before then building things back up themselves. This certainly has its merits, but especially in the modern world, CSS resets can be an overkill, resulting in a lot of extra time spent reimplementing things that weren't completely broken in the first place, like default margins, list styles, etc. @@ -154,61 +162,6 @@ In a stylesheet that contains [media query](/en-US/docs/Web/CSS/CSS_media_querie } ``` -- When a rule has multiple selectors, put each selector on a new line. This makes the selector list easier to read and can help to make code lines shorter. - - Do this: - - ```css example-good - h1, - h2, - h3 { - font-family: sans-serif; - text-align: center; - } - ``` - - Not this: - - ```css-nolint example-bad - h1, h2, h3 { - font-family: sans-serif; - text-align: center; - } - ``` - -## Space after function parameters - -Function parameters should have spaces after their separating commas, but not before: - -```css example-good -color: rgb(255, 0, 0); -background-image: linear-gradient(to bottom, red, black); -``` - -## Syntax style - -There are a variety of CSS writing styles you can use, but we prefer the expanded style, with the selector/opening brace, close brace, and each declaration on a separate line. This maximizes readability, and again, promotes consistency on MDN Web Docs. - -In addition, keep these specifics in mind: - -- Include a space between the selector(s) and the opening curly brace. -- Always include a semicolon at the end of the last declaration, even though it isn't strictly necessary. -- Put the closing curly brace on a new line. -- In each declaration, put a space after the separating colon, but not before. -- Use two spaces for code indentation. - -```css example-good -p { - color: white; - background-color: black; - padding: 1rem; -} -``` - -```css-nolint example-bad -p { color: white; background-color: black; padding: 1rem; } -``` - ## Value to turn off properties When turning off borders (and any other properties that can take `0` or `none` as values), use `0` rather than `none`: diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md index b52c8da129cf755..1401c87b876131e 100644 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md @@ -1,5 +1,5 @@ --- -title: Guidelines for styling HTML code examples +title: Guidelines for writing HTML code examples slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML page-type: mdn-writing-guide --- @@ -78,16 +78,16 @@ Omitting quotes can also cause problems. In the above example, the `alt` attribu ## Boolean attributes -Don't write out boolean attributes in full; you can just write the attribute name to set it. For example, you can write: +Don't include values for boolean attributes (but do include values for {{glossary("enumerated")}} attributes); you can just write the attribute name to set it. For example, you can write: ```html example-good -required + ``` -This is perfectly understandable and works fine; the longer version with the value is supported but not necessary: +This is perfectly understandable and works fine. If a boolean HTML attribute is present, the value is true. While including a value will work, it is not necessary and incorrect: -```html-nolint example-bad -required="required" +```html example-bad + ``` ## Case @@ -114,18 +114,6 @@ Use semantic class/ID names, and separate multiple words with hyphens. Don't use

Blah blah blah

``` -## Double quotes - -Use double quotes for HTML, not single quotes, like so: - -```html example-good -

Yes

-``` - -```html-nolint example-bad -

Nope

-``` - ## Entity references Don't use entity references unnecessarily — use the literal character wherever possible (you'll still need to escape characters like angle brackets and quote marks). @@ -142,8 +130,6 @@ Instead of:

© 2018 Me

``` -This is fine as long as you declare a UTF-8 character set. - ## HTML elements There are some rules for writing about HTML elements on MDN Web Docs. Adhering to these rules produces consistent descriptions of elements and their components and also ensures correct linking to detailed documentation. diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md index 98394b55e5bf508..0b6ddd25270f1cb 100644 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md @@ -1,5 +1,5 @@ --- -title: Guidelines for styling code examples +title: Guidelines for writing code examples slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide page-type: mdn-writing-guide --- @@ -42,38 +42,21 @@ Some more general best practices include: ## Guidelines for formatting -These guidelines for formatting code examples for MDN Web Docs are also good practices when you are coding. +Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. -### Indentation +On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/en/index.html). -- Use two spaces per tab for indentation in all code examples. -- Place the open-brace ("`{`") characters on the same line as the statement that opens the block. +Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. -```html example-good -
-

This is my paragraph.

-
-``` +These MDN Web Docs guidelines for formatting code examples are also good practices when you are coding. -```js example-good -function myFunc() { - if (thingy) { - console.log("Yup, that worked."); - } -} -``` +### Choosing a syntax language -### Spacing +To ensure proper formatting and syntax highlighting of code blocks, writers must specify the language of the code block they are writing in. See [Example code blocks in MDN Markdown](/en-us/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#Example_code_blocks) for a list of languages supported by MDN, as well as details on how to request a new language. -Add a space between a control statement or loop keyword and its opening parenthesis. +If the code block is pseudo-code, the output of a command, or otherwise not a programming language, explicitly set the language to `plain`. -```js example-good -if (condition) { - /* handle the condition */ -} else { - /* handle the "else" case */ -} -``` +> **Warning:** if the desired language is not yet supported by MDN, do **not** set the language of a code block to a similar language, as doing so may have unintended side effects with Prettier formatting and syntax highlighting. ### Code line length @@ -124,15 +107,13 @@ const toolkitProfileService = Components.classes[ ### Code block height -Code blocks should be as long as they need to be, but no longer. Ideally, aim for something short like 15-25 lines. If a code block is going to be a lot longer, consider just showing the most useful snippet, and link to the full example on a GitHub repo or codepen, say. +Code blocks should be as long as they need to be, but no longer. Ideally, aim for something short, like 15-25 lines. If a code block is going to be a lot longer, consider just showing the most useful snippet, and link to the complete example on a GitHub repo or CodePen, say. #### Inline code formatting -Use the {{HTMLElement("code")}} tags to mark up function names, variable names, and method names. -For example: "the `frenchText()` function". +Use inline code syntax (\`) to mark up function names, variable names, and method names. For example: "the `frenchText()` function". -**Method names should be followed by a pair of parentheses.** For example, `doSomethingUseful()`. -The parentheses help differentiate methods from other code terms. +**Method names should be followed by a pair of parentheses**: for example, `doSomethingUseful()`. The parentheses help differentiate methods from other code terms. ## Guidelines for proper rendering @@ -160,18 +141,18 @@ These guidelines should be followed to ensure that the code examples you write d color: rgb(248, 242, 230); ``` -- If you have to use hex colors, then use lower-case: +- For hex colors, use the short form where relevant: ```css example-good color: #058ed9; - color: #a39a92; + color: #a39a92c1; + color: #ff0; + color: #fbfa; ``` -- Use the short form where relevant: - - ```css example-good - color: #ff0; - color: #fff; + ```css-nolint example-bad + color: #ffff00; + color: #ffbbffaa; ``` ### Mark rendered examples as good or bad diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/javascript/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/javascript/index.md index 6c90b501eabfeee..f4f053a48cd05a9 100644 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/javascript/index.md +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/javascript/index.md @@ -1,5 +1,5 @@ --- -title: Guidelines for styling JavaScript code examples +title: Guidelines for writing JavaScript code examples slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript page-type: mdn-writing-guide --- @@ -24,10 +24,6 @@ Prettier formats all the code and keeps the style consistent. Nevertheless, ther You can use new features once every major browser — Chrome, Edge, Firefox, and Safari — supports them. -### Spacing and indentation - -Mark indentation with _2 spaces_. Don't use the tab character. The end-of-line character is `\n`, the Unix convention. To help you, we have included an [`.editorconfig`](https://editorconfig.org/) file in the repository. Many editors read its content and use it to configure their behavior. - ## Arrays ### Array creation diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md index 3f0d23eb35f5adb..27093a58d6c2c0a 100644 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md @@ -1,22 +1,36 @@ --- -title: Guidelines for styling shell prompt code examples +title: Guidelines for writing shell prompt code examples slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell page-type: mdn-writing-guide --- {{MDNSidebar}} -A shell is a program that waits for you to type in a command and then press the return key. To indicate which commands you should type, content on MDN Web Docs lists them in a code block, similar to code examples. Such a block looks like this: +The following guidelines cover how to write Shell prompt code examples for MDN Web Docs. + +## What is a "shell" + +A shell is a program that waits for you to type in a command and then press the return key. To indicate which commands you should type, content on MDN Web Docs lists them in a code block, similar to code examples. + +Such a block looks like this: ```bash example-good # This may take a while... -hg clone https://hg.mozilla.org/mozilla-central/ firefox -cd firefox +git clone https://github.com/mdn/content +cd content ``` -The following guidelines cover how to write Shell prompt code examples for MDN Web Docs. +## General guidelines for shell prompt code examples + +### Choosing a format + +Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. + +On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/en/index.html). + +Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. -## General guidelines for shell prompt examples +### Writing shell code blocks When writing a shell code block: diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/index.md index 52203189a4f0e92..19a7bf6db224d78 100644 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/index.md +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/index.md @@ -150,7 +150,7 @@ The following checklist is good to keep in mind while writing and reviewing cont - **Review page structure**: Review the page to ensure that it's structured properly for the [type of page](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types) it is . Be sure every section that it should have is present and has appropriate content. - **Ensure completeness**: Review sections to ensure that no information is missing. Ensure that all parameters are listed and explained. Ensure that any exceptions are covered — this is a particularly common place where content is missing. - **Ensure all concepts are fully fleshed-out**: It's easy to give a quick explanation of something, but make sure that all the nuances are covered. Are there special cases? Are there any known restrictions that the reader might need to know about? - - **Add examples**: There should be examples covering all parameters or at least the parameters (or properties, or attributes) that users from the beginner-through-intermediate range are likely to use, as well as any advanced ones that require extra explanation. Each example should be preceded with an overview of what the example will do, what additional knowledge might be needed to understand it, and so forth. After the example (or interspersed among pieces of the example) should be text explaining how the code works. Don't skimp on the details and the handling of errors in examples. Keep in mind that users _will_ copy and paste your example to use in their own projects, and your code _will_ wind up used on production sites! See our [code example guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide) for more useful information. + - **Add examples**: There should be examples covering all parameters or at least the parameters (or properties, or attributes) that users from the beginner-through-intermediate range are likely to use, as well as any advanced ones that require extra explanation. Each example should be preceded with an overview of what the example will do, what additional knowledge might be needed to understand it, and so forth. After the example (or interspersed among pieces of the example) should be text explaining how the code works. Don't skimp on the details or the handling of errors in examples. Keep in mind that users _will_ copy and paste your example to use in their own projects, and your code _will_ wind up used on production sites! See our [code example guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide) for more useful information. - **Explain use cases**: If there are particularly common use cases for the feature being described, talk about them! Instead of assuming that a user will figure out that the method being documented can be used to solve a common development problem, actually add a section about that use case with an example and text explaining how the example works. - **Add image information**: Include proper [`alt`](/en-US/docs/Web/HTML/Element/img#alt) text on all images and diagrams. This text, as well as captions on tables and other figures, counts because spiders can't crawl images, and so `alt` text tells search engine crawlers what content the embedded media contains. > **Note:** It is not recommended to include too many keywords or keywords not related to the feature in an attempt to manipulate search engine rankings; this type of behavior is easy to spot and tends to be penalized. @@ -415,7 +415,7 @@ A page on MDN Web Docs can contain more than one code example. The following lis - If you are working with a large piece of example code, it may make sense to break it up into smaller logical parts so that they can be described individually. - When adding [live samples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples) , it's helpful to be aware that all of the {{HTMLElement("pre")}} blocks in the area that contains the sample are concatenated together before running the example, which lets you break any or all of the HTML, CSS, and JavaScript into multiple segments, each optionally with its own descriptions, headings, and so forth. This makes documenting code incredibly powerful and flexible. -To learn about how to style or format code examples for MDN Web Docs, see [Guidelines for styling code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). +To learn about how to style or format code examples for MDN Web Docs, see [Guidelines for styling code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). ### External links