mathdatech/Python
1
0
Fork 0
mirror of https://github.com/TheAlgorithms/Python.git synced 2025-02-20 00:02:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

Readability of CONTRIBUTING.md (#1422)

Browse Source 
* Readability of guidelines

* Update README.md
This commit is contained in:
John Law 2019-10-23 04:07:50 +08:00 committed by GitHub
parent 5fd868c460
commit 56830255ca
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 47 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
CONTRIBUTING.md
View File

@ -30,25 +30,32 @@ Your contribution will be tested by our [automated testing on Travis CI](https:/
We want your work to be readable by others; therefore, we encourage you to note the following:
- Please write in Python 3.7+. __print()__ is a function in Python 3 so __print "Hello"__ will _not_ work but __print("Hello")__ will.
- Please focus hard on naming of functions, classes, and variables. Help your reader by using __descriptive names__ that can help you to remove redundant comments.
- Single letter variable names are _old school_ so please avoid them unless their life only spans a few lines.
- Expand acronyms because __gcd()__ is hard to understand but __greatest_common_divisor()__ is not.
- Please follow the [Python Naming Conventions](https://pep8.org/#prescriptive-naming-conventions) so variable_names and function_names should be lower_case, CONSTANTS in UPPERCASE, ClassNames should be CamelCase, etc.
- Single letter variable names are _old school_ so please avoid them unless their life only spans a few lines.
- Expand acronyms because __gcd()__ is hard to understand but __greatest_common_divisor()__ is not.
- Please follow the [Python Naming Conventions](https://pep8.org/#prescriptive-naming-conventions) so variable_names and function_names should be lower_case, CONSTANTS in UPPERCASE, ClassNames should be CamelCase, etc.
- We encourage the use of Python [f-strings](https://realpython.com/python-f-strings/#f-strings-a-new-and-improved-way-to-format-strings-in-python) where the make the code easier to read.
- Please consider running [__psf/black__](https://github.com/python/black) on your Python file(s) before submitting your pull request. This is not yet a requirement but it does make your code more readable and automatically aligns it with much of [PEP 8](https://www.python.org/dev/peps/pep-0008/). There are other code formatters (autopep8, yapf) but the __black__ style is now the recommendation of the Python Core Team. To use it,
```bash
pip3 install black # only required the first time
black .
```
- Please consider running [__psf/black__](https://github.com/python/black) on your Python file(s) before submitting your pull request. This is not yet a requirement but it does make your code more readable and automatically aligns it with much of [PEP 8](https://www.python.org/dev/peps/pep-0008/). There are other code formatters (autopep8, yapf) but the __black__ style is now the recommendation of the Python Core Team. To use it,
```bash
pip3 install black # only required the first time
black .
```
- All submissions will need to pass the test __flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics__ before they will be accepted so if possible, try this test locally on your Python file(s) before submitting your pull request.
```bash
pip3 install flake8 # only required the first time
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
```
```bash
pip3 install flake8 # only required the first time
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
```
- Original code submission require docstrings or comments to describe your work.
@ -93,9 +100,10 @@ We want your work to be readable by others; therefore, we encourage you to note
```
These doctests will be run by pytest as part of our automated testing so please try to run your doctests locally and make sure that they are found and pass:
```bash
python3 -m doctest -v my_submission.py
```
```bash
python3 -m doctest -v my_submission.py
```
The use of the Python builtin __input()__ function is **not** encouraged:
@ -110,44 +118,43 @@ We want your work to be readable by others; therefore, we encourage you to note
```python
starting_value = int(input("Please enter a starting value: ").strip())
```
The use of [Python type hints](https://docs.python.org/3/library/typing.html) is encouraged for function parameters and return values. Our automated testing will run [mypy](http://mypy-lang.org) so run that locally before making your submission.
```python
def sumab(a: int, b: int) --> int:
```python
def sumab(a: int, b: int) --> int:
pass
```
- [__list comprehensions and generators__](https://docs.python.org/3/tutorial/datastructures.html#list-comprehensions) are preferred over the use of `lambda`, `map`, `filter`, `reduce` but the important thing is to demonstrate the power of Python in code that is easy to read and maintain.
- [__List comprehensions and generators__](https://docs.python.org/3/tutorial/datastructures.html#list-comprehensions) are preferred over the use of `lambda`, `map`, `filter`, `reduce` but the important thing is to demonstrate the power of Python in code that is easy to read and maintain.
- Avoid importing external libraries for basic algorithms. Only use those libraries for complicated algorithms.
- If you need a third party module that is not in the file __requirements.txt__, please add it to that file as part of your submission.
#### Other Standard While Submitting Your Work
- File extension for code should be `.py`. Jupiter notebook files are acceptable in machine learning algorithms.
- Please avoid creating new directories if at all possible. Try to fit your work into the existing directory structue.
- Strictly use snake_case (underscore_separated) in your file_name, as it will be easy to parse in future using scripts.
- Please avoid creating new directories if at all possible. Try to fit your work into the existing directory structure.
- If possible, follow the standard *within* the folder you are submitting to.
If possible, follow the standard *within* the folder you are submitting to.
- If you have modified/added code work, make sure the code compiles before submitting.
- If you have modified/added documentation work, ensure your language is concise and contains no grammar errors.
- Do not update the README.md or DIRECTORY.md file which will be periodically autogenerated by our Travis CI processes.
- Add a corresponding explanation to [Algorithms-Explanation](https://github.com/TheAlgorithms/Algorithms-Explanation) (Optional but recommended).
- All submissions will be tested with [__mypy__](http://www.mypy-lang.org) so we encourage to add [__Python type hints__](https://docs.python.org/3/library/typing.html) where it makes sense to do so.
- Most importantly,
- Most importantly,
- **Be consistent in the use of these guidelines when submitting.**
- **Join** [Gitter](https://gitter.im/TheAlgorithms) **now!**
- Happy coding!
Writer [@poyea](https://github.com/poyea), Jun 2019.

12
README.md
View File

@ -1,4 +1,5 @@
# The Algorithms - Python
[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg?logo=paypal&style=flat-square)](https://www.paypal.me/TheAlgorithms/100) 
[![Build Status](https://img.shields.io/travis/TheAlgorithms/Python.svg?label=Travis%20CI&logo=travis&style=flat-square)](https://travis-ci.com/TheAlgorithms/Python) 
[![LGTM](https://img.shields.io/lgtm/alerts/github/TheAlgorithms/Python.svg?label=LGTM&logo=LGTM&style=flat-square)](https://lgtm.com/projects/g/TheAlgorithms/Python/alerts) 
@ -6,6 +7,7 @@
[![contributions welcome](https://img.shields.io/static/v1.svg?label=Contributions&message=Welcome&color=0059b3&style=flat-square)](https://github.com/TheAlgorithms/Python/blob/master/CONTRIBUTING.md) 
![](https://img.shields.io/github/repo-size/TheAlgorithms/Python.svg?label=Repo%20size&style=flat-square) 
<!--[![Tested on Python 3.7](https://img.shields.io/badge/Tested%20-Python%203.7-blue.svg?logo=python&style=flat-square)]( https://www.python.org/downloads) &nbsp;-->
### All algorithms implemented in Python (for education)
These implementations are for learning purposes. They may be less efficient than the implementations in the Python standard library.
@ -14,12 +16,16 @@ These implementations are for learning purposes. They may be less efficient than
Read our [Contribution Guidelines](CONTRIBUTING.md) before you contribute.
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg?style=flat-square)](https://gitpod.io/#https://github.com/TheAlgorithms/Python)
## Community Channel
We're on [Gitter](https://gitter.im/TheAlgorithms)! Please join us.
## Algorithms
## List of Algorithms
See our [directory](DIRECTORY.md).
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg?style=flat-square)](https://gitpod.io/#https://github.com/TheAlgorithms/Python)