From 4d5932c20223649b2cb39ca2326d8352528cfa26 Mon Sep 17 00:00:00 2001 From: "Queen Vinyl Da.i'gyu-Kazotetsu" Date: Mon, 17 Jul 2023 16:46:59 -0700 Subject: [PATCH 1/4] Overhaul code example guidelines --- REVIEWING.md | 2 +- files/en-us/_redirects.txt | 35 ++++++---- files/en-us/glossary/html5/index.md | 2 +- .../css/building_blocks/organizing/index.md | 2 +- .../mdn/community/pull_requests/index.md | 2 +- files/en-us/mdn/writing_guidelines/index.md | 2 +- .../page_structures/code_examples/index.md | 4 +- .../css/index.md | 69 +++---------------- .../html/index.md | 24 ++----- .../index.md | 65 +++++++---------- .../javascript/index.md | 8 +-- .../code_examples/shell/index.md | 43 ++++++++++++ .../code_style_guide/shell/index.md | 29 -------- .../writing_style_guide/index.md | 4 +- .../reference/statements/const/index.md | 2 +- .../reference/statements/let/index.md | 2 +- 16 files changed, 115 insertions(+), 180 deletions(-) rename files/en-us/mdn/writing_guidelines/writing_style_guide/{code_style_guide => code_examples}/css/index.md (81%) rename files/en-us/mdn/writing_guidelines/writing_style_guide/{code_style_guide => code_examples}/html/index.md (92%) rename files/en-us/mdn/writing_guidelines/writing_style_guide/{code_style_guide => code_examples}/index.md (76%) rename files/en-us/mdn/writing_guidelines/writing_style_guide/{code_style_guide => code_examples}/javascript/index.md (98%) create mode 100644 files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/shell/index.md delete mode 100644 files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md diff --git a/REVIEWING.md b/REVIEWING.md index 6062a357498fbca..361d779a22ca2f7 100644 --- a/REVIEWING.md +++ b/REVIEWING.md @@ -208,6 +208,6 @@ for all their help. - [@vkWeb](https://github.com/vkWeb/) [get in touch with us]: https://developer.mozilla.org/en-US/docs/MDN/Community/Contributing/Getting_started#what_can_i_do_to_help -[mdn code example guidelines]: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +[mdn code example guidelines]: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples [mdn writing style guide]: https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Writing_style_guide [MDN Web Docs chat rooms]: https://developer.mozilla.org/en-US/docs/MDN/Community/Communication_channels diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index 46bb397dc644ea8..53c6ac17310da3a 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -5413,7 +5413,7 @@ /en-US/docs/MDN/Community/Issues/Issue_triage /en-US/docs/MDN/Community/Issues /en-US/docs/MDN/Community/Users_teams /en-US/docs/MDN/Community/Roles_teams /en-US/docs/MDN/Contribute/Changelog /en-US/docs/MDN/Changelog -/en-US/docs/MDN/Contribute/Code_sample_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +/en-US/docs/MDN/Contribute/Code_sample_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples /en-US/docs/MDN/Contribute/Content /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Contribute/Content/Content_blocks /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN /en-US/docs/MDN/Contribute/Content/Custom_macros /en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros @@ -5437,13 +5437,13 @@ /en-US/docs/MDN/Contribute/Guidelines /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Contribute/Guidelines/Best_practices /en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete /en-US/docs/MDN/Contribute/Guidelines/CSS_style_guide /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/General /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/JavaScript /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/Shell /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell -/en-US/docs/MDN/Contribute/Guidelines/Code_samples /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/General /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/JavaScript /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/Shell /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell +/en-US/docs/MDN/Contribute/Guidelines/Code_samples /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples /en-US/docs/MDN/Contribute/Guidelines/Content /en-US/docs/MDN/Writing_guidelines/What_we_write /en-US/docs/MDN/Contribute/Guidelines/Content_blocks /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN /en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions /en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete @@ -5489,7 +5489,7 @@ /en-US/docs/MDN/Contribute/Processes/Matching_features_to_browser_version https://github.com/mdn/browser-compat-data/blob/main/docs/matching-browser-releases/index.md /en-US/docs/MDN/Contribute/Processes/Matching_features_to_browser_versiosn https://github.com/mdn/browser-compat-data/blob/main/docs/matching-browser-releases/index.md /en-US/docs/MDN/Contribute/Processes/Short_surveys /en-US/docs/MDN/Contribute -/en-US/docs/MDN/Contribute/Sample_app_coding_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +/en-US/docs/MDN/Contribute/Sample_app_coding_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples /en-US/docs/MDN/Contribute/Sample_server /en-US/docs/MDN /en-US/docs/MDN/Contribute/Structures /en-US/docs/MDN/Writing_guidelines/Page_structures /en-US/docs/MDN/Contribute/Structures/:-ms-input-placeholder_pseudo-class /en-US/docs/Web/CSS/:placeholder-shown @@ -5541,12 +5541,12 @@ /en-US/docs/MDN/Getting_started /en-US/docs/MDN/Community/Contributing/Getting_started /en-US/docs/MDN/Guidelines /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Guidelines/CSS_style_guide /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN -/en-US/docs/MDN/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide -/en-US/docs/MDN/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS -/en-US/docs/MDN/Guidelines/Code_guidelines/General /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide -/en-US/docs/MDN/Guidelines/Code_guidelines/HTML /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML -/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript -/en-US/docs/MDN/Guidelines/Code_guidelines/Shell /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell +/en-US/docs/MDN/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples +/en-US/docs/MDN/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS +/en-US/docs/MDN/Guidelines/Code_guidelines/General /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples +/en-US/docs/MDN/Guidelines/Code_guidelines/HTML /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML +/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript +/en-US/docs/MDN/Guidelines/Code_guidelines/Shell /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell /en-US/docs/MDN/Guidelines/Content /en-US/docs/MDN/Writing_guidelines/What_we_write /en-US/docs/MDN/Guidelines/Conventions_definitions /en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete /en-US/docs/MDN/Guidelines/Does_this_belong_on_MDN /en-US/docs/MDN/Writing_guidelines/What_we_write @@ -5609,6 +5609,11 @@ /en-US/docs/MDN/Writing_guidelines/Howto/Tag /en-US/docs/MDN/Writing_guidelines/Howto /en-US/docs/MDN/Writing_guidelines/Research_technology /en-US/docs/MDN/Writing_guidelines/Howto/Research_technology /en-US/docs/MDN/Writing_guidelines/What_we_write/Inclusion_criteria /en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion +/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples +/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS +/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML +/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript +/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell /en-US/docs/MDN/Yari https://github.com/mdn/yari/tree/main/docs /en-US/docs/MDN_at_ten /en-US/docs/MDN/At_ten /en-US/docs/MDN_at_ten/Contributing_to_MDN /en-US/docs/MDN/Contribute diff --git a/files/en-us/glossary/html5/index.md b/files/en-us/glossary/html5/index.md index 46668cd56093ed5..a0f96e377111736 100644 --- a/files/en-us/glossary/html5/index.md +++ b/files/en-us/glossary/html5/index.md @@ -10,7 +10,7 @@ The term HTML5 is essentially a buzzword that refers to a set of modern web tech You may sometimes hear about "new HTML5 elements", or find HTML5 described as a new version of HTML. HTML5 was the successor to previous HTML versions and introduced new elements and capabilities to the language on top of the previous version, HTML 4.01, as well as improving or removing some existing functionality. However, as a Living Standard HTML now has no version. The up-to-date specification can be found at [html.spec.whatwg.org/](https://html.spec.whatwg.org/). -Any modern site should use the [HTML doctype](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML#doctype) — this will ensure that you are using the latest version of HTML. +Any modern site should use the [HTML doctype](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML#doctype) — this will ensure that you are using the latest version of HTML. > **Note:** Until 2019, the {{glossary("W3C")}} published a competing HTML5 standard with version numbers. Since [28 May 2019](https://www.w3.org/blog/news/archives/7753), the WHATWG Living Standard was announced by the W3C as the sole version of HTML. diff --git a/files/en-us/learn/css/building_blocks/organizing/index.md b/files/en-us/learn/css/building_blocks/organizing/index.md index c5750410ef07f23..c30570a4af1d8a7 100644 --- a/files/en-us/learn/css/building_blocks/organizing/index.md +++ b/files/en-us/learn/css/building_blocks/organizing/index.md @@ -47,7 +47,7 @@ Here are some general suggestions for ways to keep your stylesheets organized an If you are working with a team on an existing project, the first thing to check is whether the project has an existing style guide for CSS. The team style guide should always win over your own personal preferences. There often isn't a right or wrong way to do things, but consistency is important. -For example, have a look at the [CSS guidelines for MDN code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS). +For example, have a look at the [CSS guidelines for MDN code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS). ### Keep it consistent diff --git a/files/en-us/mdn/community/pull_requests/index.md b/files/en-us/mdn/community/pull_requests/index.md index bf25b98eaf5b676..73e92b3356865cd 100644 --- a/files/en-us/mdn/community/pull_requests/index.md +++ b/files/en-us/mdn/community/pull_requests/index.md @@ -117,7 +117,7 @@ Do leave the door open to the author to ask for help, especially new contributor ### Reviewing a pull request -When it comes to the changes in a pull request, content and prose must adhere to the [MDN Writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide) and example code must follow the [code style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). +When it comes to the changes in a pull request, content and prose must adhere to the [MDN Writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide) and example code must follow the [code examples guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples). When you are reviewing a pull request, you should: diff --git a/files/en-us/mdn/writing_guidelines/index.md b/files/en-us/mdn/writing_guidelines/index.md index 6dc73bf75f3cafc..bcf4b90031aecd5 100644 --- a/files/en-us/mdn/writing_guidelines/index.md +++ b/files/en-us/mdn/writing_guidelines/index.md @@ -18,7 +18,7 @@ MDN Web Docs is an open-source project. The sections outlined below describe our - [Our writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide) - - : The writing style guide covers the language and style we use to write on MDN Web Docs. It also covers how to [format code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). + - : The writing style guide covers the language and style we use to write on MDN Web Docs. It also covers how to [format code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples). - [How to write for MDN Web Docs](/en-US/docs/MDN/Writing_guidelines/Howto) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md b/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md index f542ff3357df81e..e950206bcce3a2e 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md @@ -8,7 +8,7 @@ page-type: mdn-writing-guide On MDN, you'll see numerous code examples inserted throughout the pages to demonstrate usage of web platform features. This article discusses the different mechanisms available for adding code examples to pages, along with which ones you should use and when. -> **Note:** If you want advice on the styling and linting of code as it appears on an MDN article, rather than the different ways of including code, see our [Code style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). +> **Note:** If you want advice on the styling and linting of code as it appears on an MDN article, rather than the different ways of including code, see our [Code examples guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples). ## What types of code example are available? @@ -213,4 +213,4 @@ This looks like so when rendered: ### Tips for using GitHub live samples - You obviously need to get a suitable code sample onto the [MDN GitHub organization](https://github.com/mdn/) first. This needs to be done using Git. If you are not familiar with Git, check out our [How do I use GitHub Pages?](/en-US/docs/Learn/Common_questions/Tools_and_setup/Using_GitHub_pages) article, and [Preparing to add the data](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables) for more advanced uses. -- Your code sample needs to be suitable to show what you are trying to demonstrate — it should contain one simple example that does one thing well, should have no offensive content in it, and should follow the MDN [Code sample guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). +- Your code sample needs to be suitable to show what you are trying to demonstrate — it should contain one simple example that does one thing well, should have no offensive content in it, and should follow the MDN [Code examples guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples). 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_examples/css/index.md similarity index 81% rename from files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/css/index.md rename to files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/css/index.md index 1c3b6959eaf2c00..0fe95b8f5a42546 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_examples/css/index.md @@ -1,6 +1,6 @@ --- -title: Guidelines for styling CSS code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS +title: Guidelines for writing CSS code examples +slug: MDN/Writing_guidelines/Writing_style_guide/Code_examples/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_examples/html/index.md similarity index 92% rename from files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md rename to files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/html/index.md index b52c8da129cf755..0300766c06e8db1 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_examples/html/index.md @@ -1,6 +1,6 @@ --- -title: Guidelines for styling HTML code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML +title: Guidelines for writing HTML code examples +slug: MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML page-type: mdn-writing-guide --- @@ -81,13 +81,13 @@ Omitting quotes can also cause problems. In the above example, the `alt` attribu Don't write out boolean attributes in full; 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: -```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_examples/index.md similarity index 76% rename from files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md rename to files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/index.md index 74a9925baeb6a0d..c21b9e729ed8648 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_examples/index.md @@ -1,6 +1,6 @@ --- -title: Guidelines for styling code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +title: Guidelines for writing code examples +slug: MDN/Writing_guidelines/Writing_style_guide/Code_examples page-type: mdn-writing-guide --- @@ -10,10 +10,10 @@ The guidelines described in this article apply to the styling and formatting of For technology-specific guidelines, see the following articles: -- [HTML guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML) -- [CSS guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS) -- [JavaScript guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript) -- [Shell prompt guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell) +- [HTML guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML) +- [CSS guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS) +- [JavaScript guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript) +- [Shell prompt guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell) ## General best practices @@ -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 guidelines for formatting code examples for MDN Web Docs 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 full 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,20 +141,20 @@ 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; - ``` - -- Use the short form where relevant: - - ```css example-good color: #ff0; color: #fff; ``` + ```css-nolint example-bad + color: #ffff00; + color: #ffffff; + ``` + ### Mark rendered examples as good or bad You'll notice on this page that the code blocks that represent good practices to follow are rendered with a green check mark in the right corner, and the code blocks that demonstrate bad practices are rendered with white cross in red circle. 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_examples/javascript/index.md similarity index 98% rename from files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/javascript/index.md rename to files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/javascript/index.md index 6c90b501eabfeee..912123a3741bf6a 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_examples/javascript/index.md @@ -1,6 +1,6 @@ --- -title: Guidelines for styling JavaScript code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript +title: Guidelines for writing JavaScript code examples +slug: MDN/Writing_guidelines/Writing_style_guide/Code_examples/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_examples/shell/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/shell/index.md new file mode 100644 index 000000000000000..23230b177d9c74b --- /dev/null +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/shell/index.md @@ -0,0 +1,43 @@ +--- +title: Guidelines for writing shell prompt code examples +slug: MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell +page-type: mdn-writing-guide +--- + +{{MDNSidebar}} + +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 +``` + +## 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. + +### Writing shell code blocks + +When writing a shell code block: + +- Do not include a `$` or `>` at the beginning of a shell instruction. It confuses more than it helps and it is not useful when copying the instructions. +- Comments start with `#`. +- Choose "bash" to indicate the language in markdown. + +## See also + +[Django server-side development docs](/en-US/docs/Learn/Server-side/Django) show good practice presentation of shell prompt commands. 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 deleted file mode 100644 index 3f0d23eb35f5adb..000000000000000 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Guidelines for styling 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: - -```bash example-good -# This may take a while... -hg clone https://hg.mozilla.org/mozilla-central/ firefox -cd firefox -``` - -The following guidelines cover how to write Shell prompt code examples for MDN Web Docs. - -## General guidelines for shell prompt examples - -When writing a shell code block: - -- Do not include a `$` or `>` at the beginning of a shell instruction. It confuses more than it helps and it is not useful when copying the instructions. -- Comments start with `#`. -- Choose "bash" to indicate the language in markdown. - -## See also - -[Django server-side development docs](/en-US/docs/Learn/Server-side/Django) show good practice presentation of shell prompt commands. 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 e20a7225d2ebc35..9c4ee3f7850b171 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 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_examples) 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_examples). ### External links diff --git a/files/en-us/web/javascript/reference/statements/const/index.md b/files/en-us/web/javascript/reference/statements/const/index.md index 0e79542078299ce..fb35442e4610b20 100644 --- a/files/en-us/web/javascript/reference/statements/const/index.md +++ b/files/en-us/web/javascript/reference/statements/const/index.md @@ -53,7 +53,7 @@ const FOO; // SyntaxError: Missing initializer in const declaration The `const` declaration creates an immutable reference to a value. It does _not_ mean the value it holds is immutable — just that the variable identifier cannot be reassigned. For instance, in the case where the content is an object, this means the object's contents (e.g., its properties) can be altered. You should understand `const` declarations as "create a variable whose _identity_ remains constant", not "whose _value_ remains constant" — or, "create immutable {{glossary("binding", "bindings")}}", not "immutable values". -Many style guides (including [MDN's](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript#variable_declarations)) recommend using `const` over {{jsxref("Statements/let", "let")}} whenever a variable is not reassigned in its scope. This makes the intent clear that a variable's type (or value, in the case of a primitive) can never change. Others may prefer `let` for non-primitives that are mutated. +Many style guides (including [MDN's](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript#variable_declarations)) recommend using `const` over {{jsxref("Statements/let", "let")}} whenever a variable is not reassigned in its scope. This makes the intent clear that a variable's type (or value, in the case of a primitive) can never change. Others may prefer `let` for non-primitives that are mutated. The list that follows the `const` keyword is called a _{{glossary("binding")}} list_ and is separated by commas, where the commas are _not_ [comma operators](/en-US/docs/Web/JavaScript/Reference/Operators/Comma_operator) and the `=` signs are _not_ [assignment operators](/en-US/docs/Web/JavaScript/Reference/Operators/Assignment). Initializers of later variables can refer to earlier variables in the list. diff --git a/files/en-us/web/javascript/reference/statements/let/index.md b/files/en-us/web/javascript/reference/statements/let/index.md index c723d7208704c16..cc9845623d9e26f 100644 --- a/files/en-us/web/javascript/reference/statements/let/index.md +++ b/files/en-us/web/javascript/reference/statements/let/index.md @@ -62,7 +62,7 @@ Compared with {{jsxref("Statements/var", "var")}}, `let` declarations have the f Note that `let` is allowed as an identifier name when declared with `var` or `function` in [non-strict mode](/en-US/docs/Web/JavaScript/Reference/Strict_mode), but you should avoid using `let` as an identifier name to prevent unexpected syntax ambiguities. -Many style guides (including [MDN's](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript#variable_declarations)) recommend using {{jsxref("Statements/const", "const")}} over `let` whenever a variable is not reassigned in its scope. This makes the intent clear that a variable's type (or value, in the case of a primitive) can never change. Others may prefer `let` for non-primitives that are mutated. +Many style guides (including [MDN's](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript#variable_declarations)) recommend using {{jsxref("Statements/const", "const")}} over `let` whenever a variable is not reassigned in its scope. This makes the intent clear that a variable's type (or value, in the case of a primitive) can never change. Others may prefer `let` for non-primitives that are mutated. The list that follows the `let` keyword is called a _{{glossary("binding")}} list_ and is separated by commas, where the commas are _not_ [comma operators](/en-US/docs/Web/JavaScript/Reference/Operators/Comma_operator) and the `=` signs are _not_ [assignment operators](/en-US/docs/Web/JavaScript/Reference/Operators/Assignment). Initializers of later variables can refer to earlier variables in the list. From 8495e38e1f5505b2f17c28825c4695d2d869e013 Mon Sep 17 00:00:00 2001 From: "Queen Vinyl Da.i'gyu-Kazotetsu" Date: Mon, 24 Jul 2023 16:25:18 -0700 Subject: [PATCH 2/4] Revert document move I don't really agree with returning this to the original location, but IDC anymore. --- REVIEWING.md | 2 +- files/en-us/_redirects.txt | 35 ++++++++----------- files/en-us/glossary/html5/index.md | 2 +- .../css/building_blocks/organizing/index.md | 2 +- .../mdn/community/pull_requests/index.md | 2 +- files/en-us/mdn/writing_guidelines/index.md | 2 +- .../page_structures/code_examples/index.md | 4 +-- .../css/index.md | 2 +- .../html/index.md | 2 +- .../index.md | 10 +++--- .../javascript/index.md | 2 +- .../shell/index.md | 2 +- .../writing_style_guide/index.md | 4 +-- .../reference/statements/const/index.md | 2 +- .../reference/statements/let/index.md | 2 +- 15 files changed, 35 insertions(+), 40 deletions(-) rename files/en-us/mdn/writing_guidelines/writing_style_guide/{code_examples => code_style_guide}/css/index.md (99%) rename files/en-us/mdn/writing_guidelines/writing_style_guide/{code_examples => code_style_guide}/html/index.md (98%) rename files/en-us/mdn/writing_guidelines/writing_style_guide/{code_examples => code_style_guide}/index.md (97%) rename files/en-us/mdn/writing_guidelines/writing_style_guide/{code_examples => code_style_guide}/javascript/index.md (99%) rename files/en-us/mdn/writing_guidelines/writing_style_guide/{code_examples => code_style_guide}/shell/index.md (96%) diff --git a/REVIEWING.md b/REVIEWING.md index 361d779a22ca2f7..6062a357498fbca 100644 --- a/REVIEWING.md +++ b/REVIEWING.md @@ -208,6 +208,6 @@ for all their help. - [@vkWeb](https://github.com/vkWeb/) [get in touch with us]: https://developer.mozilla.org/en-US/docs/MDN/Community/Contributing/Getting_started#what_can_i_do_to_help -[mdn code example guidelines]: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples +[mdn code example guidelines]: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide [mdn writing style guide]: https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Writing_style_guide [MDN Web Docs chat rooms]: https://developer.mozilla.org/en-US/docs/MDN/Community/Communication_channels diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index 53c6ac17310da3a..46bb397dc644ea8 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -5413,7 +5413,7 @@ /en-US/docs/MDN/Community/Issues/Issue_triage /en-US/docs/MDN/Community/Issues /en-US/docs/MDN/Community/Users_teams /en-US/docs/MDN/Community/Roles_teams /en-US/docs/MDN/Contribute/Changelog /en-US/docs/MDN/Changelog -/en-US/docs/MDN/Contribute/Code_sample_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples +/en-US/docs/MDN/Contribute/Code_sample_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide /en-US/docs/MDN/Contribute/Content /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Contribute/Content/Content_blocks /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN /en-US/docs/MDN/Contribute/Content/Custom_macros /en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros @@ -5437,13 +5437,13 @@ /en-US/docs/MDN/Contribute/Guidelines /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Contribute/Guidelines/Best_practices /en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete /en-US/docs/MDN/Contribute/Guidelines/CSS_style_guide /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/General /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/JavaScript /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/Shell /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell -/en-US/docs/MDN/Contribute/Guidelines/Code_samples /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/General /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/JavaScript /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/Shell /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell +/en-US/docs/MDN/Contribute/Guidelines/Code_samples /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide /en-US/docs/MDN/Contribute/Guidelines/Content /en-US/docs/MDN/Writing_guidelines/What_we_write /en-US/docs/MDN/Contribute/Guidelines/Content_blocks /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN /en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions /en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete @@ -5489,7 +5489,7 @@ /en-US/docs/MDN/Contribute/Processes/Matching_features_to_browser_version https://github.com/mdn/browser-compat-data/blob/main/docs/matching-browser-releases/index.md /en-US/docs/MDN/Contribute/Processes/Matching_features_to_browser_versiosn https://github.com/mdn/browser-compat-data/blob/main/docs/matching-browser-releases/index.md /en-US/docs/MDN/Contribute/Processes/Short_surveys /en-US/docs/MDN/Contribute -/en-US/docs/MDN/Contribute/Sample_app_coding_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples +/en-US/docs/MDN/Contribute/Sample_app_coding_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide /en-US/docs/MDN/Contribute/Sample_server /en-US/docs/MDN /en-US/docs/MDN/Contribute/Structures /en-US/docs/MDN/Writing_guidelines/Page_structures /en-US/docs/MDN/Contribute/Structures/:-ms-input-placeholder_pseudo-class /en-US/docs/Web/CSS/:placeholder-shown @@ -5541,12 +5541,12 @@ /en-US/docs/MDN/Getting_started /en-US/docs/MDN/Community/Contributing/Getting_started /en-US/docs/MDN/Guidelines /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Guidelines/CSS_style_guide /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN -/en-US/docs/MDN/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples -/en-US/docs/MDN/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS -/en-US/docs/MDN/Guidelines/Code_guidelines/General /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples -/en-US/docs/MDN/Guidelines/Code_guidelines/HTML /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML -/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript -/en-US/docs/MDN/Guidelines/Code_guidelines/Shell /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell +/en-US/docs/MDN/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +/en-US/docs/MDN/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS +/en-US/docs/MDN/Guidelines/Code_guidelines/General /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +/en-US/docs/MDN/Guidelines/Code_guidelines/HTML /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML +/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript +/en-US/docs/MDN/Guidelines/Code_guidelines/Shell /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell /en-US/docs/MDN/Guidelines/Content /en-US/docs/MDN/Writing_guidelines/What_we_write /en-US/docs/MDN/Guidelines/Conventions_definitions /en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete /en-US/docs/MDN/Guidelines/Does_this_belong_on_MDN /en-US/docs/MDN/Writing_guidelines/What_we_write @@ -5609,11 +5609,6 @@ /en-US/docs/MDN/Writing_guidelines/Howto/Tag /en-US/docs/MDN/Writing_guidelines/Howto /en-US/docs/MDN/Writing_guidelines/Research_technology /en-US/docs/MDN/Writing_guidelines/Howto/Research_technology /en-US/docs/MDN/Writing_guidelines/What_we_write/Inclusion_criteria /en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion -/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples -/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS -/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML -/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript -/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell /en-US/docs/MDN/Yari https://github.com/mdn/yari/tree/main/docs /en-US/docs/MDN_at_ten /en-US/docs/MDN/At_ten /en-US/docs/MDN_at_ten/Contributing_to_MDN /en-US/docs/MDN/Contribute diff --git a/files/en-us/glossary/html5/index.md b/files/en-us/glossary/html5/index.md index a0f96e377111736..46668cd56093ed5 100644 --- a/files/en-us/glossary/html5/index.md +++ b/files/en-us/glossary/html5/index.md @@ -10,7 +10,7 @@ The term HTML5 is essentially a buzzword that refers to a set of modern web tech You may sometimes hear about "new HTML5 elements", or find HTML5 described as a new version of HTML. HTML5 was the successor to previous HTML versions and introduced new elements and capabilities to the language on top of the previous version, HTML 4.01, as well as improving or removing some existing functionality. However, as a Living Standard HTML now has no version. The up-to-date specification can be found at [html.spec.whatwg.org/](https://html.spec.whatwg.org/). -Any modern site should use the [HTML doctype](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML#doctype) — this will ensure that you are using the latest version of HTML. +Any modern site should use the [HTML doctype](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML#doctype) — this will ensure that you are using the latest version of HTML. > **Note:** Until 2019, the {{glossary("W3C")}} published a competing HTML5 standard with version numbers. Since [28 May 2019](https://www.w3.org/blog/news/archives/7753), the WHATWG Living Standard was announced by the W3C as the sole version of HTML. diff --git a/files/en-us/learn/css/building_blocks/organizing/index.md b/files/en-us/learn/css/building_blocks/organizing/index.md index c30570a4af1d8a7..c5750410ef07f23 100644 --- a/files/en-us/learn/css/building_blocks/organizing/index.md +++ b/files/en-us/learn/css/building_blocks/organizing/index.md @@ -47,7 +47,7 @@ Here are some general suggestions for ways to keep your stylesheets organized an If you are working with a team on an existing project, the first thing to check is whether the project has an existing style guide for CSS. The team style guide should always win over your own personal preferences. There often isn't a right or wrong way to do things, but consistency is important. -For example, have a look at the [CSS guidelines for MDN code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS). +For example, have a look at the [CSS guidelines for MDN code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS). ### Keep it consistent diff --git a/files/en-us/mdn/community/pull_requests/index.md b/files/en-us/mdn/community/pull_requests/index.md index 73e92b3356865cd..bf25b98eaf5b676 100644 --- a/files/en-us/mdn/community/pull_requests/index.md +++ b/files/en-us/mdn/community/pull_requests/index.md @@ -117,7 +117,7 @@ Do leave the door open to the author to ask for help, especially new contributor ### Reviewing a pull request -When it comes to the changes in a pull request, content and prose must adhere to the [MDN Writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide) and example code must follow the [code examples guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples). +When it comes to the changes in a pull request, content and prose must adhere to the [MDN Writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide) and example code must follow the [code style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). When you are reviewing a pull request, you should: diff --git a/files/en-us/mdn/writing_guidelines/index.md b/files/en-us/mdn/writing_guidelines/index.md index bcf4b90031aecd5..6dc73bf75f3cafc 100644 --- a/files/en-us/mdn/writing_guidelines/index.md +++ b/files/en-us/mdn/writing_guidelines/index.md @@ -18,7 +18,7 @@ MDN Web Docs is an open-source project. The sections outlined below describe our - [Our writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide) - - : The writing style guide covers the language and style we use to write on MDN Web Docs. It also covers how to [format code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples). + - : The writing style guide covers the language and style we use to write on MDN Web Docs. It also covers how to [format code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). - [How to write for MDN Web Docs](/en-US/docs/MDN/Writing_guidelines/Howto) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md b/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md index e950206bcce3a2e..f542ff3357df81e 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md @@ -8,7 +8,7 @@ page-type: mdn-writing-guide On MDN, you'll see numerous code examples inserted throughout the pages to demonstrate usage of web platform features. This article discusses the different mechanisms available for adding code examples to pages, along with which ones you should use and when. -> **Note:** If you want advice on the styling and linting of code as it appears on an MDN article, rather than the different ways of including code, see our [Code examples guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples). +> **Note:** If you want advice on the styling and linting of code as it appears on an MDN article, rather than the different ways of including code, see our [Code style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). ## What types of code example are available? @@ -213,4 +213,4 @@ This looks like so when rendered: ### Tips for using GitHub live samples - You obviously need to get a suitable code sample onto the [MDN GitHub organization](https://github.com/mdn/) first. This needs to be done using Git. If you are not familiar with Git, check out our [How do I use GitHub Pages?](/en-US/docs/Learn/Common_questions/Tools_and_setup/Using_GitHub_pages) article, and [Preparing to add the data](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables) for more advanced uses. -- Your code sample needs to be suitable to show what you are trying to demonstrate — it should contain one simple example that does one thing well, should have no offensive content in it, and should follow the MDN [Code examples guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples). +- Your code sample needs to be suitable to show what you are trying to demonstrate — it should contain one simple example that does one thing well, should have no offensive content in it, and should follow the MDN [Code sample guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/css/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/css/index.md similarity index 99% rename from files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/css/index.md rename to files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/css/index.md index 81fbfb8c26fd11c..cb0f139747bb611 100644 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/css/index.md +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/css/index.md @@ -1,6 +1,6 @@ --- title: Guidelines for writing CSS code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS +slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS page-type: mdn-writing-guide --- diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/html/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md similarity index 98% rename from files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/html/index.md rename to files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md index 0300766c06e8db1..b9dcfa368202662 100644 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/html/index.md +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md @@ -1,6 +1,6 @@ --- title: Guidelines for writing HTML code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML +slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML page-type: mdn-writing-guide --- diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md similarity index 97% rename from files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/index.md rename to files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md index 2bc2afcc0459f67..0409f4f11963955 100644 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/index.md +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md @@ -1,6 +1,6 @@ --- title: Guidelines for writing code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_examples +slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide page-type: mdn-writing-guide --- @@ -10,10 +10,10 @@ The guidelines described in this article apply to the styling and formatting of For technology-specific guidelines, see the following articles: -- [HTML guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML) -- [CSS guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS) -- [JavaScript guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript) -- [Shell prompt guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell) +- [HTML guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML) +- [CSS guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS) +- [JavaScript guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript) +- [Shell prompt guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell) ## General best practices diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/javascript/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/javascript/index.md similarity index 99% rename from files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/javascript/index.md rename to files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/javascript/index.md index 912123a3741bf6a..f4f053a48cd05a9 100644 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/javascript/index.md +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/javascript/index.md @@ -1,6 +1,6 @@ --- title: Guidelines for writing JavaScript code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript +slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript page-type: mdn-writing-guide --- diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/shell/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md similarity index 96% rename from files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/shell/index.md rename to files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md index 23230b177d9c74b..01a95bad1802a42 100644 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/shell/index.md +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md @@ -1,6 +1,6 @@ --- title: Guidelines for writing shell prompt code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell +slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell page-type: mdn-writing-guide --- 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 30e3a64c4d51b51..8ef8c02bdbdd5a2 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_examples) 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 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. - **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_examples). +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 diff --git a/files/en-us/web/javascript/reference/statements/const/index.md b/files/en-us/web/javascript/reference/statements/const/index.md index fb35442e4610b20..0e79542078299ce 100644 --- a/files/en-us/web/javascript/reference/statements/const/index.md +++ b/files/en-us/web/javascript/reference/statements/const/index.md @@ -53,7 +53,7 @@ const FOO; // SyntaxError: Missing initializer in const declaration The `const` declaration creates an immutable reference to a value. It does _not_ mean the value it holds is immutable — just that the variable identifier cannot be reassigned. For instance, in the case where the content is an object, this means the object's contents (e.g., its properties) can be altered. You should understand `const` declarations as "create a variable whose _identity_ remains constant", not "whose _value_ remains constant" — or, "create immutable {{glossary("binding", "bindings")}}", not "immutable values". -Many style guides (including [MDN's](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript#variable_declarations)) recommend using `const` over {{jsxref("Statements/let", "let")}} whenever a variable is not reassigned in its scope. This makes the intent clear that a variable's type (or value, in the case of a primitive) can never change. Others may prefer `let` for non-primitives that are mutated. +Many style guides (including [MDN's](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript#variable_declarations)) recommend using `const` over {{jsxref("Statements/let", "let")}} whenever a variable is not reassigned in its scope. This makes the intent clear that a variable's type (or value, in the case of a primitive) can never change. Others may prefer `let` for non-primitives that are mutated. The list that follows the `const` keyword is called a _{{glossary("binding")}} list_ and is separated by commas, where the commas are _not_ [comma operators](/en-US/docs/Web/JavaScript/Reference/Operators/Comma_operator) and the `=` signs are _not_ [assignment operators](/en-US/docs/Web/JavaScript/Reference/Operators/Assignment). Initializers of later variables can refer to earlier variables in the list. diff --git a/files/en-us/web/javascript/reference/statements/let/index.md b/files/en-us/web/javascript/reference/statements/let/index.md index cc9845623d9e26f..c723d7208704c16 100644 --- a/files/en-us/web/javascript/reference/statements/let/index.md +++ b/files/en-us/web/javascript/reference/statements/let/index.md @@ -62,7 +62,7 @@ Compared with {{jsxref("Statements/var", "var")}}, `let` declarations have the f Note that `let` is allowed as an identifier name when declared with `var` or `function` in [non-strict mode](/en-US/docs/Web/JavaScript/Reference/Strict_mode), but you should avoid using `let` as an identifier name to prevent unexpected syntax ambiguities. -Many style guides (including [MDN's](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript#variable_declarations)) recommend using {{jsxref("Statements/const", "const")}} over `let` whenever a variable is not reassigned in its scope. This makes the intent clear that a variable's type (or value, in the case of a primitive) can never change. Others may prefer `let` for non-primitives that are mutated. +Many style guides (including [MDN's](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript#variable_declarations)) recommend using {{jsxref("Statements/const", "const")}} over `let` whenever a variable is not reassigned in its scope. This makes the intent clear that a variable's type (or value, in the case of a primitive) can never change. Others may prefer `let` for non-primitives that are mutated. The list that follows the `let` keyword is called a _{{glossary("binding")}} list_ and is separated by commas, where the commas are _not_ [comma operators](/en-US/docs/Web/JavaScript/Reference/Operators/Comma_operator) and the `=` signs are _not_ [assignment operators](/en-US/docs/Web/JavaScript/Reference/Operators/Assignment). Initializers of later variables can refer to earlier variables in the list. From 0506a285f72a68fe41c091078ce09161c8207321 Mon Sep 17 00:00:00 2001 From: "Queen Vinyl Da.i'gyu-Kazotetsu" Date: Wed, 26 Jul 2023 16:10:42 -0700 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Estelle Weyl --- .../writing_style_guide/code_style_guide/html/index.md | 6 +++--- .../writing_style_guide/code_style_guide/index.md | 4 ++-- .../mdn/writing_guidelines/writing_style_guide/index.md | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) 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 b9dcfa368202662..ba7c3ef6d7c2bc2 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 @@ -78,13 +78,13 @@ 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 - + ``` -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 example-bad 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 0409f4f11963955..f0ee9fc35c4822d 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 @@ -48,7 +48,7 @@ On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. -These guidelines for formatting code examples for MDN Web Docs are also good practices when you are coding. +These MDN Web Docs guidelines for formatting code examples are also good practices when you are coding. ### Choosing a syntax language @@ -107,7 +107,7 @@ 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 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 8ef8c02bdbdd5a2..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. From a3ee037a634d086699f6bb7d4aa5e4b0d366d0a9 Mon Sep 17 00:00:00 2001 From: "Queen Vinyl Da.i'gyu-Kazotetsu" Date: Wed, 26 Jul 2023 16:17:24 -0700 Subject: [PATCH 4/4] Apply suggestions from code review --- .../writing_style_guide/code_style_guide/html/index.md | 2 +- .../writing_style_guide/code_style_guide/index.md | 6 +++--- .../writing_style_guide/code_style_guide/shell/index.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) 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 ba7c3ef6d7c2bc2..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 @@ -87,7 +87,7 @@ Don't include values for boolean attributes (but do include values for {{glossar 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 example-bad - + ``` ## Case 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 f0ee9fc35c4822d..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 @@ -145,14 +145,14 @@ These guidelines should be followed to ensure that the code examples you write d ```css example-good color: #058ed9; - color: #a39a92; + color: #a39a92c1; color: #ff0; - color: #fff; + color: #fbfa; ``` ```css-nolint example-bad color: #ffff00; - color: #ffffff; + color: #ffbbffaa; ``` ### Mark rendered examples as good or bad 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 01a95bad1802a42..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 @@ -16,8 +16,8 @@ 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 ``` ## General guidelines for shell prompt code examples