coding standard gold
Opened this issue · 8 comments
npm run browser-build
npm test
inline doc -> README.md
tests
compatibility
jsdoc3
snippets
I'm now looking at the current 'gold standard' list. I'm surprised that it prescribes so many specific tools. For example, could the gold ribbon not be earned by a project that uses:
- Grunt rather than Gulp, or
- Jasmine rather than Mocha, or
- Drone rather than Travis, or
- JsLint rather than JsHint, or
- HTML or ThreeJS rather than D3?
These specific choices do not seem, to me, marks of quality, but of personal preference or convenience. What do I think should be part of the gold standard? I'll name a few things that come to mind:
- user documentation,
- API documentation (extra points if it is generated from the code itself),
- usage examples,
- automated unit tests with high code coverage,
- automated integration tests,
- tool-enforced code-consistency (e.g. jslint/hint/etc.),
- publicly visible continuous integration,
- an npm presence.
These seem, to me, objective standards of quality. Note that my only concession to a specific tool is npm. That's just because having every BioJS component in the same system helps interoperability, and does not preclude the package from also being listed in, e.g., Bower.
👍
You are absolutely right. The idea of the "gold(en) standard" was to state important aspects like "having a good documentation" and not use jsdoc.
However some people had the concern that new comers would be very unfamiliar and that we should give recommendation for each of these points.
Thank you very much @mhelvens, @jmvillaveces, @ljgarcia and @timruffles for stating this problem.
The current version isn't perfect - so feel free to comment here with your feedback or edit it directly ;-)
That looks like a good starting point.
I was also meaning to ask you about the BioJS (Node) coding style guide. Same story as the specific tools, really: do we want to encourage specific coding styles, e.g., tabs versus spacing? I would say no. Such style-guides are only practical within large projects with many people working on the same code.
A consistent style within a project could be seen as a plus, though. I guess this falls under the heading of code consistency (even though it is broader than jslint/hint). I'm sure there are open-source tools that can reformat code based on a manual configuration, i.e., prettifiers, though I can't name any off the top of my head. (I use the WebStorm IDE for this myself, but it's paid software with a much broader scope.)
the BioJS (Node) coding style guide
I agree - "tool-enforced code consistency" is the right term. My opinion is that if people don't know which coding style they should use (>60%), we recommend them to use the same. So the style guide acts as convenience like the biojs-events package.
I'm sure there are open-source tools that can reformat code based on a manual configuration
jsbeautifier looks very promising. Here we could (same as above) also provide a config for people who don't have a special taste.
Agreed.
It seems that these fixes all come down to the clear separation of:
- requirements and recommendations, and
- tips about specific tools and techniques for developers who do not yet have a preference.
I believe this separation should be maintained in all our documentation.
Status update: I restructured this into "conventions" where we show violations (e. g. documentation or tests) with the help of io-ratings and gold standards like continuous integration which are only a recommendation.