Javascript: Consider turning on exception ignoreEOLComments for no-multi-spaces rule

[dietergeerts]

When you have a longer chain in your code, like an observable chain, or promise one, or lodash flow one, we sometimes comment the chain to make it more understandable what happens and why each step is there. To make it easier to read, we align the comments, but the current rule settings give errors on this.

So why is the ignoreEOLComments turned off? Is there a special reason for this? Imho, it should be turned on, to make it possible to align comments like:

myObservable
  .pipe(
    map(inACertainWayFunction),              // Step explanation
    filter(byPropBFunction),                 // Step explanation
    distinctUntilChanged(comparisonFunction) // Step explanation
  );

[ljharb]

What's the value in visual alignment there? The guide prefers this:

myObservable
  .pipe(
    map(inACertainWayFunction), // Step explanation
    filter(byPropBFunction), // Step explanation
    distinctUntilChanged(comparisonFunction) // Step explanation
  );

In other words, never visually align anything except with semantic indentation.

[dietergeerts]

The value: easier to read. Readability is very important, and in the example, it's easier to read the steps than to figure out the actual code. When the comments tell you enough, you can continue. Without lining them out, you do have to read all the code first, so then the comments become less useful.

[ljharb]

My initial reaction is that anywhere comments appear and are explaining "what" (as opposed to "why" or history/motivation), that's a failure of the code to be self-documenting enough. In other words, I think the code itself should be readable enough that no comments are required to know what it's doing.

[hornta]

Can you try and write it like this? Does that help the readability?

myObservable
  .pipe(
    map(inACertainWayFunction), //              Step explanation
    filter(byPropBFunction), //                 Step explanation
    distinctUntilChanged(comparisonFunction) // Step explanation
  );

[dietergeerts]

@ljharb, It's actually the 'why' they explain. In very long difficult chains, we'll always explain the functional part behind the steps, so we know 'why' they are there, that's what I mean with step explanation. Off course it's bad to explain what the code does, that should be clear by the line of code itself.

Some real code of the current project to better show what I mean:

/**
 * Switch to single getter to enable single source of truth.
 *
 * @param {ModelStore<*>} store
 * @returns {function(Observable<OBJ>): Observable<OBJ>}
 * @template OBJ
 */
export function switchGet(store) {

  return source => source
    .do(setModelCache(store.readModel)) // Set reader cache for individual model,
    .do(nextOn(store.modelUpdated))     // And throw event, as may be already subscribed...
    .map(get('id'))                     // Get the id from the model to use in the get.
    .switchMap(store.getModel)          // Then use get to enable single source of truth.
    .distinctUntilChanged(isEqual);     // Because of internal (re-)subscription, we got multiple updates...
}