JavaScript Chat Summary: December 3, 2019

Below is a summary of the discussion from this week’s JavaScript chat (agendaSlack Transcript).

Have a topic for discussion for the next meeting? Leave a suggested edit on next week’s agenda.

Follow-Up: Types Checking

(Slack conversation, previous meeting summary)

A new tracking issue was created for modules types effort, including some rough guidelines toward the bottom of the comment.

@aduth shared a small pull request to demonstrate how this task can look for simpler modules, as a point of reference for others who might be interested in contributed.

Last week, there was some discussion about necessary changes for the automated documentation tool (“docgen”). A summary of these findings was shared on the corresponding issue.

Discussion:

  • @gziolo mentions that the effectiveness this process will need to be validated by other volunteers.
  • @aduth suggests a simple approach to testing types in a file by adding // @ts-check as a line at the top of a file.
  • @gziolo suggests it could be helpful to create a screencast to demonstrate the effort, referencing a similar example shared by @mkaz.

Action items:

  • Consider recording a screencast to demonstrate the effort of converting a package to be typed. (Tentatively owned by @mkaz)

JSDoc Standards

(Slack conversation)

Using JSDoc for types validation will force us to write better, more accurate JSDoc, which may require some new or updated guidelines (see current guidelines).

A few specific examples are mentioned:

  • Deemphasis of Backbone guidelines
  • Updates with respect to modernized syntaxes, files structure
  • TypeScript-specific JSDoc syntax extensions

Discussion:

  • Since these observations are limited to Gutenberg-exclusive use of ES2015 modules for files structuring and TypeScript tooling, it may make more sense for these supplementary guidelines to exist in the Gutenberg documentation.
  • Taking cues from the coding guidelines, the handbook standard can serve as a base upon which Gutenberg-specific recommendations can extend. Common guidelines should live in the JSDoc handbook, proposed for migration as appropriate similar to that done previously for Gutenberg JavaScript standards.

Actions:

  • Propose standards documentation for JSDoc syntax relevant for clarifying uncertainties in the types-checking effort. (Owned by @aduth)

#core-js, #javascript