From 6be700e0807717eb43d06aabbbb3d90961636533 Mon Sep 17 00:00:00 2001 From: Zachary Patten Date: Thu, 17 Oct 2019 21:34:09 -0400 Subject: [PATCH] Updating Markdown Files --- .github/Pages/Code Standards.md | 34 ++++++++++++++--------- .github/Pages/Development Environments.md | 20 ++++--------- CONTRIBUTING.md | 24 ++++------------ README.md | 1 + 4 files changed, 32 insertions(+), 47 deletions(-) diff --git a/.github/Pages/Code Standards.md b/.github/Pages/Code Standards.md index d35cb7f9..36621338 100644 --- a/.github/Pages/Code Standards.md +++ b/.github/Pages/Code Standards.md @@ -1,7 +1,21 @@ # Code Standards -These code standards are goals of the code in the Towel project. They are not set in stone, but they -should be followed if possible. +This is just some syntax preference notes for Towel. They are not strict rules and will not be enforced at this time. Just follow them if it makes sense. :) + +### Runtime Algorithmic Complexity + +One of the goals of Towel is to have members documented with algoritmic complexity using the `runtime` XML tag. Here is the notation in use: + +- O(...): upper bound +- Ω(...): lower bound +- Θ(...): upper and lower bound +- ε(...): expected average + +Examples: +- `/// O(1)` the member has constant time +- `/// O(n), Ω(1), ε(1)` the member may have to iterate n items, but it will generally run in constant time +- `/// Θ(n)` the member iterates n items +- `/// Θ(n^2)` the member iterates n items and has a nested loop ### Tabs @@ -9,18 +23,12 @@ Please use tabs rather than spaces. ### Fields First -When declaring types, all fields (instance + static + const) should come before other members and be -outside any "#region" or other code groupings. This makes it easy for people to understand the structure -and purpose of a type. +When declaring types, all fields (instance + static + const) should come before other members and be outside any "#region" or other code groupings. This makes it easy for people to understand the structure and purpose of a type. -### Runtime Algorithmic Complexity +### Internal Over Private -One of the goals of the project is to have members documented with algoritmic complexity using the "runtime" XML tag. -Here is the notation in use: +In general, prefer `internal` over `private`. If people want to access `internal` members for whatever reason, they can just download the code and add an `InternalsVisibleTo` attribute to the code so they can access internal members. -- O(...): upper bound -- Ω(...): lower bound -- Θ(...): upper and lower bound -- ε(...): expected average +### Expression Boded Members Are Prefered -_Note: Runtime documentation is not a requirement for pull requests._ +In general, prefer expression body definition syntax `member => expression;` over traditional C# syntax `member { expression; }` where applicable. diff --git a/.github/Pages/Development Environments.md b/.github/Pages/Development Environments.md index 19a1fc18..8a75e25b 100644 --- a/.github/Pages/Development Environments.md +++ b/.github/Pages/Development Environments.md @@ -1,13 +1,8 @@ # Development Environments -If you are new to C# development, here are some notes on recommended development environments -to help get you started with the Towel project. - ## Visual Studio 2019 -[Visual Studio 2019](https://visualstudio.microsoft.com/) is the recommended development environment. -The *Community* edition is free. Just open the "Towel.sln" file in Visual Studio 2019 and the code should -build without any additional steps. +[Visual Studio 2019](https://visualstudio.microsoft.com/) is the recommended development environment. The *Community* edition is free. Just open the "Towel.sln" file in Visual Studio 2019 and the code should build without any additional steps.
Optional Settings @@ -67,9 +62,7 @@ Keep tabs = true ## Visual Studio Code -[Visual Studio Code](https://visualstudio.microsoft.com/) is _not_ the recommended development environment, -but it you can use it as well. Visual Studio Code is a free program. After installing Visual Studio Code, you -will need to add the following extensions to use it for the Towel project: +[Visual Studio Code](https://visualstudio.microsoft.com/) is _not_ the recommended development environment, but it you can use it as well. Visual Studio Code is a free program. After installing Visual Studio Code, you will need to add the following extensions to use it for the Towel project: - **ms-vscode.csharp** - _Reason: support for C#_ @@ -80,18 +73,15 @@ will need to add the following extensions to use it for the Towel project: - _Reason: support for MSTest unit testing_ - _Optional: this is only necessary if you plan on running the unit tests_ -Once the extensions are installed, open the root folder of the repository. +Open the root folder of the Towel repository in Visual Studio Code. -_Note: The Collision Detection 3D example is a .NET Framework project (not .NET Core) and therefore is not -supported for debugging in Visual Studio Code. You will have to run that example without debugging. All the -other examples are .NET Core and fully compatible for debugging in Visual Studio Code._ +_Note: The Collision Detection 3D example is a .NET Framework project (not .NET Core) and therefore is not supported for debugging in Visual Studio Code. You will have to run that example without debugging. All the other examples are .NET Core and fully compatible for debugging in Visual Studio Code._
Optional Settings

-These are some notes about settings I like to use when I code in Visual Studio Code. They are completely optional. -All settings can be modified in the ".vscode/settings.json" file. +These are some notes about settings I like to use when I code in Visual Studio Code. They are completely optional. All settings can be modified in the ".vscode/settings.json" file. - "editor.insertSpaces": false, - "editor.renderWhitespace": "all", diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96b37abe..3683cbfe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,27 +1,13 @@ -# Contributing to the Towel project - -## How Can You Help? +# Contributing to Towel #### Open An Issue -If you notice anything that can be improved about the Towel project please [create a new issue](https://github.com/ZacharyPatten/Towel/issues/new/choose) on the GitHub repository. This could be a bug fix, a possible enhancement, or anything else regarding the project. Creating an issue is just a public post that anyone can see and comment on. - -#### Share The Project - -Sharing the project with other programmers is a big help. The more eyes on the project the more input can be provided to make the project better. - -#### Writing Tutorials, Articles, and Blog Posts - -Towel is lacking proper documentation. Writing tutorials, articles, and/or blog posts about the project would be a big help. Let the [project developer(s)](https://github.com/ZacharyPatten/Towel#developers) know about your content, and it might be linked to from the project README. - -#### Show Off How You Use Towel - -If you use the Towel in a project and are willing to show it off, message the [project developer(s)](https://github.com/ZacharyPatten/Towel#developers) and your project or branding might be linked to from the project README. Showing an active user base would be a big help. +If you notice anything in Towel that may be improved, please [create a new issue](https://github.com/ZacharyPatten/Towel/issues/new/choose) on the GitHub repository. This could be a bug fix, an enhancement, or anything else regarding the project. Creating an issue is just a public post that anyone can see and comment on. -#### Chat on Discord +#### Reference Your Content -You can chat with the developer(s) on [Discord](https://discord.gg/4XbQbwF). They can give you more specific information on what would currently benefit the project. +If you create any content relavent to Towel (blog posts, articles, tutorials, videos, a project that uses Towel, etc.), message the [project developer(s)](https://github.com/ZacharyPatten/Towel#developers) and a link to your content may be added. #### Development -If you want to help out with the development of the code, contributing will involve the standard GitHub processes of forking the code and creating a pull request. Any issues marked as [Good First Issue](https://github.com/ZacharyPatten/Towel/contribute)s will generally be the best starting points for helping out. Visual Studio 2019 is the prefered environment for development. Just open the Towel.sln file and the project should build without any configuration. +If you want to help out with the development of the code, it will involve the standard GitHub processes of forking the code and creating a pull request. Any issues marked as [Good First Issue](https://github.com/ZacharyPatten/Towel/contribute)s will generally be the best starting points for helping out. You can chat with the [project developer(s)](https://github.com/ZacharyPatten/Towel#developers) on [Discord](https://discord.gg/4XbQbwF) for more information. See the [Development Environments](https://github.com/ZacharyPatten/Towel/blob/master/.github/Pages/Development%20Environments.md) page for information on the recommended development environemnts. There is a [Coding Standards](https://github.com/ZacharyPatten/Towel/blob/master/.github/Pages/Code%20Standards.md) page, but the coding standards will not be strongly enforced at this time. diff --git a/README.md b/README.md index c79fe844..3bc728fc 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ Towel is a C# .Net Standard libary intended to add core functionality that is mi ## Pages - [Development Environments](https://github.com/ZacharyPatten/Towel/blob/master/.github/Pages/Development%20Environments.md) +- [Contributing](https://github.com/ZacharyPatten/Towel/blob/master/CONTRIBUTING.md) - [Code Documentation](https://zacharypatten.github.io/Towel/Documentation) - _Note: This page still needs a lot of work_ - [Coding Standards](https://github.com/ZacharyPatten/Towel/blob/master/.github/Pages/Code%20Standards.md)