hyphacoop/handbook

add a code style guide

Opened this issue · 4 comments

uditvira commented

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

tripledoublev commented

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

writerly03 commented

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

deniseyu commented

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

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