Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add a code style guide #162

Open
uditvira opened this issue Apr 1, 2022 · 4 comments
Open

add a code style guide #162

uditvira opened this issue Apr 1, 2022 · 4 comments
Assignees
Labels
comms Back office communications tasks

Comments

@uditvira
Copy link
Member

uditvira commented Apr 1, 2022

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

@tripledoublev
Copy link
Member

tripledoublev commented Aug 3, 2023

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

@writerly03
Copy link
Contributor

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

@deniseyu
Copy link

deniseyu commented Aug 3, 2023

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
Copy link
Member

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

@tripledoublev tripledoublev added the comms Back office communications tasks label Oct 4, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
comms Back office communications tasks
Projects
None yet
Development

No branches or pull requests

4 participants