airbnb / airbnb/javascript

Clarification for Inline Comments

Open
#1,506 7 comments 0 reactions 0 assignees View on GitHub
editorial pull request wanted
Dominant language
JavaScript
Stars
148k
Forks
26.6k
PR merge metrics
No merged PRs in 30d

Description

Thanks for the excellent style guide!

One thing that is not explicitly defined by the guide is inline comments. Can a section on this topic be added to the "Comments" section block, please?

For example,
```
let foo = 145; // This is modified below in the "baz()" function
```

Is this a legal line in the airbnb style?

And the follow-up question: if it is not legal, then I assume that the correct fix to have it be moved above, like this?

```
// This is modified below in the "baz()" function
let foo = 145;
```

Yet another follow-up question: if inline comments are legal, then what is the correct fix for in-line comments that make the line extend past 100 character? Like the following:

```
// This is a comment describing the following block of variable initializations
let foo = 123; // used in various contexts, but mostly for soccer games, basketball, and football games
let bar = 456; // used only for horse races; it is explicitly reset at the beginning of the "endRace()" function
let baz = 789; // used only for car races; it will be overwritten once we reach the "oilChange()" function
```

If it were moved above, it would overlap with the block comment header. So then does it make the most sense to move them down to the next line, like this?

```
// This is a comment describing the following block of variable initializations
let foo = 123;
// used in various contexts, but mostly for soccer games, basketball, and football games
let bar = 456;
// used only for horse races; it is explicitly reset at the beginning of the "endRace()" function
let baz = 789;
// used only for car races; it will be overwritten once we reach the "oilChange()" function
```

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the existing "Comments" section of the style guide and the seven-comment thread. Determine whether the thread establishes guidance for inline comments and long lines; done means documenting a maintainer-approved rule with examples, or identifying that a decision is still needed.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.