Skip to content

Commit 8f2c993

Browse files
authored
CONTRIBUTING.md: Fix comments about the black formatter (TheAlgorithms#1841)
* CONTRIBUTING.md: Fix comments about the black formatter Fixes TheAlgorithms#1840 * Update CONTRIBUTING.md * Update CONTRIBUTING.md
1 parent 1b65309 commit 8f2c993

File tree

1 file changed

+11
-28
lines changed

1 file changed

+11
-28
lines changed

CONTRIBUTING.md

+11-28
Original file line numberDiff line numberDiff line change
@@ -37,13 +37,9 @@ We want your work to be readable by others; therefore, we encourage you to note
3737
- Expand acronyms because __gcd()__ is hard to understand but __greatest_common_divisor()__ is not.
3838
- 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.
3939

40-
41-
4240
- 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.
4341

44-
45-
46-
- 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,
42+
- 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,
4743

4844
```bash
4945
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
5753
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
5854
```
5955

60-
61-
6256
- Original code submission require docstrings or comments to describe your work.
6357

6458
- More on docstrings and comments:
6559

66-
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.
60+
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.
6761

6862
The following are considered to be bad and may be requested to be improved:
6963

@@ -73,29 +67,27 @@ We want your work to be readable by others; therefore, we encourage you to note
7367

7468
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.
7569

76-
We encourage you to put docstrings inside your functions but please pay attention to indentation of docstrings. The following is acceptable in this case:
70+
We encourage you to put docstrings inside your functions but please pay attention to indentation of docstrings. The following is a good example:
7771

7872
```python
79-
def sumab(a, b):
73+
def sum_ab(a, b):
8074
"""
81-
This function returns the sum of two integers a and b
82-
Return: a + b
75+
Return the sum of two integers a and b.
8376
"""
8477
return a + b
8578
```
8679

8780
- 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_.
8881

8982
```python
90-
def sumab(a, b):
83+
def sum_ab(a, b):
9184
"""
92-
This function returns the sum of two integers a and b
93-
Return: a + b
94-
>>> sumab(2, 2)
85+
Returns the sum of two integers a and b
86+
>>> sum_ab(2, 2)
9587
4
96-
>>> sumab(-2, 3)
88+
>>> sum_ab(-2, 3)
9789
1
98-
>>> sumab(4.9, 5.1)
90+
>>> sum_ab(4.9, 5.1)
9991
10.0
10092
"""
10193
return a + b
@@ -125,15 +117,11 @@ We want your work to be readable by others; therefore, we encourage you to note
125117

126118
```python
127119
def sumab(a: int, b: int) --> int:
128-
pass
120+
pass
129121
```
130122

131-
132-
133123
- [__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.
134124

135-
136-
137125
- Avoid importing external libraries for basic algorithms. Only use those libraries for complicated algorithms.
138126
- 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.
139127

@@ -143,17 +131,12 @@ We want your work to be readable by others; therefore, we encourage you to note
143131
- Strictly use snake_case (underscore_separated) in your file_name, as it will be easy to parse in future using scripts.
144132
- Please avoid creating new directories if at all possible. Try to fit your work into the existing directory structure.
145133
- If possible, follow the standard *within* the folder you are submitting to.
146-
147-
148-
149134
- If you have modified/added code work, make sure the code compiles before submitting.
150135
- If you have modified/added documentation work, ensure your language is concise and contains no grammar errors.
151136
- Do not update the README.md or DIRECTORY.md file which will be periodically autogenerated by our Travis CI processes.
152137
- Add a corresponding explanation to [Algorithms-Explanation](https://github.com/TheAlgorithms/Algorithms-Explanation) (Optional but recommended).
153138
- 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.
154139

155-
156-
157140
- Most importantly,
158141
- **Be consistent in the use of these guidelines when submitting.**
159142
- **Join** [Gitter](https://gitter.im/TheAlgorithms) **now!**

0 commit comments

Comments
 (0)