Require new or amended core code to have explanatory JSDoc blocks

This is something that massively frustrates me - as I'm sure it does other potential contributors.

Most of the Node-RED core code is impenetrable to most people. Even for experienced developers, the friction involved in trying to understand how things are working internally means that there are just a tiny number of people who can contribute to the ongoing improvement of core code.

I appreciate that it will not be feasible to have a massive update but I would request that you update requirements for future changes such that changes should require at least a JSDoc comment block for each function providing at least a minimalist explanation of what it does.

Certainly, any new functions added to core should have a full JSDoc block such that, at some future point, more sensible and complete API documentation can be created easily.

For API functions that should not be used outside of core code (by node creators for example), the function can be marked as private.

It would probably also be helpful to publish an eslint config adjusted to Node-RED coding standards so that any contributors can not only write code that meets standards but can also make lint updates (e.g. replacing var statements) to assist with keeping the codebase to modern standards.

See NR5: Project Infrastructure Updates · Issue #5363 · node-red/node-red · GitHub for some of this planned in NR5

1 Like

Thanks Nick.

If there is anything specific I can add to that issue, I'd be happy to do so.