gbowne1/reactsocialnetwork

[feature]: Create a Coding Style and Naming Conventions document.

manuel12 opened this issue · 6 comments

manuel12 commented

Is your feature request related to a problem? Please describe.

I know for personal experience that naming things can take important time from developers that could otherwise be spend fixing and building things. A document outlining our coding style and naming conventions would standardize this freeing devs of having to worry on how to name things.

Some things we need to document naming conventions for:

  • Components
  • Pages
  • Style files
  • CSS style rules (right now we use a form of BEM naming convention)
  • Routes
  • Database tables
  • UI test names
  • API test names

...among others.

Describe the solution you would like

Will create such a document and refer in the main README.md and CONTRIBUTING.md documents.

Describe the alternatives you have tried

N/A

Additional context

No response

gbowne1 commented

@manuel12

I did make a Developer doc in the Wiki tab of this project. Its pretty basic. I suppose one could update it and include all the tidbits of info and just link to it from README.

I would eventually like to migrate all of our docs to Wiki anyways. GitHub's Wiki uses plain Markdown so it should be easy and you can clone or fork it as a separate repo and commit push etc directly to it.

manuel12 commented

@manuel12

I did make a Developer doc in the Wiki tab of this project. Its pretty basic. I suppose one could update it and include all the tidbits of info and just link to it from README.

I would eventually like to migrate all of our docs to Wiki anyways. GitHub's Wiki uses plain Markdown so it should be easy and you can clone or fork it as a separate repo and commit push etc directly to it.

Yes. I will update the wiki doc and link to it from the readme.

  • 👍1
  • 🎉1
  • ❤️1
gbowne1 commented

I find that in my most people really wouldn't "read" the README.md so it should be simple. So, when we redo it, it should make it much simpler.

I feel like the GitHub wiki is a much cleaner solution. CodeBooker needs the same solution too.

The README.md should be pretty brief but include:

  • Shields.io shields and badges (links might need to be cleaned up)
  • Links to Wiki Docs
  • Links to Internationalization Docs (Docs in other languages)
  • Project Maintainers/Collaborators (need to install the https://www.npmjs.com/package/all-contributors package.)
  • A brief "About this project.."
  • Features & User stuff

Wiki docs could and should include:

  • Installation
  • Testing/QA/QC
  • Collaboration, Contribution,
  • Code Style docs
  • Design references
  • Internationalization Docs (Docs in other languages)

Thoughts, comments, suggestions, ideas?

  • 👍1
manuel12 commented

@gbowne1 In my latest PR I update the readme by removing a lot of text and instead adding links to wiki pages where the user can find the same information as before in the readme: #307

gbowne1 commented

Good idea, I saw that! 👍 Good work.

Should make docs maintainable without having to clutter up the repo with docs, and of course its still Markdown. 💯