One goal is to make it easy (and fun!) enough to work with the code that others will use it and contribute to it - voluntarily, not because they need to for a job or a class. Clarity and brevity are virtues, as is functionality.
The code, in itself, is an instrument for the education of users (and contributors). Readers should be enlightened about the purpose of the code, and at a more granular level focus on “why” rather than “what”. I use “how” comments roughly in proportion to the black-magic-ness of the implementation, for myself as well as others.
Remember that the code is only part of a larger system. Without good docs, runtime UX, community outreach, responses to bug reports and feature requests, etc., the system is less impactful. Code is not an end in itself; only the means to an end. (when thinking like an OSS maintainer; code may of course be an end-in-itself in other ways)
From my own experience, ‘think like an open-source maintainer’:
One goal is to make it easy (and fun!) enough to work with the code that others will use it and contribute to it - voluntarily, not because they need to for a job or a class. Clarity and brevity are virtues, as is functionality.
The code, in itself, is an instrument for the education of users (and contributors). Readers should be enlightened about the purpose of the code, and at a more granular level focus on “why” rather than “what”. I use “how” comments roughly in proportion to the black-magic-ness of the implementation, for myself as well as others.
Remember that the code is only part of a larger system. Without good docs, runtime UX, community outreach, responses to bug reports and feature requests, etc., the system is less impactful. Code is not an end in itself; only the means to an end. (when thinking like an OSS maintainer; code may of course be an end-in-itself in other ways)
That’s amazing! Great idea!