search

hyphacoop / handbook

Member's handbook describing the vision, processes, and culture of Hypha 🌿🍄
https://handbook.hypha.coop
Creative Commons Attribution Share Alike 4.0 International
27 stars 4 forks source link

add a code style guide #162

Open uditvira opened 2 years ago

uditvira commented 2 years ago

maybe just reference and adopt an existing one e.g., https://google.github.io/styleguide/

tripledoublev commented 1 year ago

Google's markdown style guide seems like a good candidate: https://google.github.io/styleguide/docguide/style.html

writerly03 commented 1 year ago

I feel like this is a good question for the engineering roundtable?

deniseyu commented 1 year ago

That reminds me that we should write up the outcome of the last roundtable re: tooling - cc @YurkoWasHere maybe we can pair on this in the next few weeks

tripledoublev commented 1 year ago

The Philosophy page from the guide shared above contains some interesting snippets

Readable source text

  • Plain text not only suffices, it is superior. Markdown itself is not essential to this formula, but it is the best and most widely supported solution right now. HTML is generally not encouraged.

  • Content and presentation should not mingle. It should always be possible to ditch the renderer and read the essential information at source. Users should never have to touch the presentation layer if they don’t want to.

  • Portability and future-proofing leave room for the unimagined integrations to come, and are best achieved by keeping the source as human-readable as possible.

  • Static content is better than dynamic, because content should not depend on the features of any one server. However, fresh is better than stale. We strive to balance these needs.

Beyond the engineering roundtable, I would like to surface this issue to the communications WG to see what would be the best way to communicate guidelines regarding code style