From 8f2c9932e09948a046f8d11b18f7c634ee4161fe Mon Sep 17 00:00:00 2001 From: Christian Clauss Date: Wed, 8 Apr 2020 12:27:11 +0200 Subject: [PATCH] CONTRIBUTING.md: Fix comments about the black formatter (#1841) * CONTRIBUTING.md: Fix comments about the black formatter Fixes #1840 * Update CONTRIBUTING.md * Update CONTRIBUTING.md --- CONTRIBUTING.md | 39 +++++++++++---------------------------- 1 file changed, 11 insertions(+), 28 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d939108a4..2aa4be9e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,13 +37,9 @@ We want your work to be readable by others; therefore, we encourage you to note - 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, +- 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__ formatter is now hosted by the Python Software Foundation. To use it, ```bash pip3 install black # only required the first time @@ -57,13 +53,11 @@ We want your work to be readable by others; therefore, we encourage you to note flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics ``` - - - Original code submission require docstrings or comments to describe your work. - More on docstrings and comments: - If you are using a Wikipedia article or some other source material to create your algorithm, please add the URL in a docstring or comment to help your reader. + If you used a Wikipedia article or some other source material to create your algorithm, please add the URL in a docstring or comment to help your reader. The following are considered to be bad and may be requested to be improved: @@ -73,13 +67,12 @@ We want your work to be readable by others; therefore, we encourage you to note This is too trivial. Comments are expected to be explanatory. For comments, you can write them above, on or below a line of code, as long as you are consistent within the same piece of code. - We encourage you to put docstrings inside your functions but please pay attention to indentation of docstrings. The following is acceptable in this case: + We encourage you to put docstrings inside your functions but please pay attention to indentation of docstrings. The following is a good example: ```python - def sumab(a, b): + def sum_ab(a, b): """ - This function returns the sum of two integers a and b - Return: a + b + Return the sum of two integers a and b. """ return a + b ``` @@ -87,15 +80,14 @@ We want your work to be readable by others; therefore, we encourage you to note - Write tests (especially [__doctests__](https://docs.python.org/3/library/doctest.html)) to illustrate and verify your work. We highly encourage the use of _doctests on all functions_. ```python - def sumab(a, b): + def sum_ab(a, b): """ - This function returns the sum of two integers a and b - Return: a + b - >>> sumab(2, 2) + Returns the sum of two integers a and b + >>> sum_ab(2, 2) 4 - >>> sumab(-2, 3) + >>> sum_ab(-2, 3) 1 - >>> sumab(4.9, 5.1) + >>> sum_ab(4.9, 5.1) 10.0 """ return a + b @@ -125,15 +117,11 @@ We want your work to be readable by others; therefore, we encourage you to note ```python def sumab(a: int, b: int) --> int: - pass + 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. - - - 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. @@ -143,17 +131,12 @@ We want your work to be readable by others; therefore, we encourage you to note - 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 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, - **Be consistent in the use of these guidelines when submitting.** - **Join** [Gitter](https://gitter.im/TheAlgorithms) **now!**