Writing detailed comments is an important component of writing software.

However, every language and framework has its own syntax for writing comments. This can make it difficult for developers to know how to write comments when they're learning a new language or library.

The JavaScript library React has some notoriously bizarre syntax for writing comments. In this article, I'm going to explain how to write comments in React JSX.

This article starts by explaining what React and JSX are; if you're already familiar with React ecosystem and only want to learn about how to write React JSX comments, click here to skip to the relevant section of this article.

What is React?

To understand how to write comments in React JSX, you must first understand what that means. We'll introduce React first and then briefly explain what JSX is in the context of the broader React ecosystem.

React.js is the world's most popular JavaScript framework for developing user interfaces. React is an open-source project that was originally created by Facebook. To date, Facebook employs a small dedicated team that works on the framework full-time.

The core functionality of React is the ability to create components - which are JavaScript classes or functions that accept inputs and return a React element that renders a specific portion of the user interface.

Here is an example of a very basic React component that renders an H2 tag that says "I am a title!":

class Title extends React.Component {
  constructor() {
    super();
    this.state = {color: "#135485"};
  }
  render() {
    return <h2>I am a title!</h2>;
  }
}

A mature React application will have many dozens - if not hundreds - of components. In fact, large websites like Airbnb, Atlassian, Cloudflare, and Dropbox use React to build their user interfaces.

This is because React is actually tremendously useful. First of all, the reusability of React components makes building complex applications faster.

You'll also benefit from the support of Facebook, which uses React for its own products that are used by billions of people. Knowing that a library can handle Facebook's scale is very reassuring when you are building applications that may need to serve millions of requests concurrently.

Now that you understand React, let's discuss JSX within the context of the broader React framework.

What is React JSX?

React JSX is a special type of syntax used when writing React code. It is considered to be an XML- or HTML-like syntax, which means it is very similar to HTML in appearance.

JSX is used by preprocessors or transpilers (like Babel) ot transform HTML into JavaScript objects that a JavaScript engine and parse and render to the document object model (DOM).

The React documentation uses the following example to illustrate what JSX is. Note that the variable being created is neither a string nor HTML; instead, it is JSX:

const element = <h1>Hello, world!</h1>;

One of the main benefits of JSX is that it allows you to interpolate variables with HTML-like code. An example (again, sourced from the React documentation) is below:

const name = 'Josh Perez';

const element = <h1>Hello, {name}</h1>;

ReactDOM.render(

  element,

  document.getElementById('root')

);

Now that you have a basic understanding of what JSX is, let's explore why writing JSX comments can be so problematic.

The Problems With Writing React JSX Comments

When trying to write JSX comments in React, developers often run into one of two problems.

First, trying to write HTML comments inside of JSX will cause JSX to think that the comments are real DOM nodes. An example is below:

render(){

return(

<div>

	<!-- JSX will think this is a DOM node!!! -->

</div>

)

}

Second, regular JavaScript comments get parsed as text and will actually appear in your web application! This popular StackOverflow question has a great example of this, where a developer includes a normal HTML comment (using the // syntax) that actually gets rendered on the website.

So how do we properly write comments in React JSX? We explore this in the next section.

How To Write React JSX Comments

To write proper comments in React JSX, you need to do things:

1. Write a block comment in HTML, which starts with /* and ends with */
2. Wrap that block comment in curly braces

An example of a proper comment in React JSX is below:

<div className="dropdown"> 
{/* This is an example of a proper comment in React JSX */} 
    <Button whenClicked={this.handleClick} className="btn-default" title={this.props.title} subTitleClassName="caret"></Button> 
    <UnorderedList /> 
</div>

Here is another example:

render () { 
return <DeleteResourceButton 
    {/*Here is the comment!!*/} 
    onDelete={this.onDelete.bind(this)} 
    message="This file will be deleted from the server." 
    /> 
}

Final Thoughts

This article demonstrated how to write React JSX comments without running into the issues commonly experienced by React developers.

While the syntax is arguably a bit bizarre, I hope this guide was helpful for you.

Feel free to refer back to it if you ever get stuck in the future.