You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+51-37Lines changed: 51 additions & 37 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,26 +23,38 @@ We are very happy that you consider implementing algorithms and data structure f
23
23
24
24
We appreciate any contribution, from fixing a grammar mistake in a comment to implementing complex algorithms. Please read this section if you are contributing your work.
25
25
26
+
Your contribution will be tested by our [automated testing on Travis CI](https://travis-ci.org/TheAlgorithms/Python/pull_requests) to save time and mental energy. After you have submitted your pull request, you should see the Travis tests start to run at the bottom of your submission page. If those tests fail, then click on the ___details___ button try to read through the Travis output to understand the failure. If you do not understand, please leave a comment on your submission page and a community member will try to help.
27
+
26
28
#### Coding Style
27
29
28
30
We want your work to be readable by others; therefore, we encourage you to note the following:
29
31
30
-
- Please write in Python 3.x.
31
-
- Please consider running [__python/black__](https://github.com/python/black) on your Python file(s) before submitting your pull request. This is not a requirement but it does make your code more readable. There are other code formatters (autopep8, yapf) but the __black__ style is now the recommendation of the Python core team. To use it,
32
+
- Please write in Python 3.7+. __print()__ is a function in Python 3 so __print "Hello"__ will _not_ work but __print("Hello")__ will.
33
+
34
+
- 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.
35
+
- Single letter variable names are _old school_ so please avoid them unless their life only spans a few lines.
36
+
- Expand acronyms because __gcd()__ is hard to understand but __greatest_common_divisor()__ is not.
37
+
- 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.
38
+
39
+
- 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.
40
+
41
+
- 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,
32
42
```bash
33
43
pip3 install black # only required the first time
34
-
black my-submission.py
44
+
black .
35
45
```
36
46
37
47
- 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.
48
+
```bash
49
+
pip3 install flake8 # only required the first time
- If you know [PEP 8](https://www.python.org/dev/peps/pep-0008/) already, you will have no problem in coding style, though we do not follow it strictly. Read the remaining section and have fun coding!
40
-
41
-
- Always use 4 spaces to indent.
53
+
- Original code submission require docstrings or comments to describe your work.
42
54
43
-
- Original code submission requires comments to describe your work.
55
+
- More on docstrings and comments:
44
56
45
-
- More on comments and docstrings:
57
+
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.
46
58
47
59
The following are considered to be bad and may be requested to be improved:
48
60
@@ -52,69 +64,72 @@ We want your work to be readable by others; therefore, we encourage you to note
52
64
53
65
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.
54
66
55
-
*Sometimes, docstrings are avoided.* This will happen if you are using some editors and not careful with indentation:
67
+
We encourage you to put docstrings inside your functions but please pay attention to indentation of docstrings. The following is acceptable in this case:
56
68
57
69
```python
70
+
def sumab(a, b):
71
+
"""
72
+
This function returns the sum of two integers a and b
73
+
Return: a + b
58
74
"""
59
-
This function sums a and b
60
-
"""
61
-
def sum(a, b):
62
75
return a + b
63
76
```
64
77
65
-
However, if you insist to use docstrings, we encourage you to put docstrings inside functions. Also, please pay attention to indentation to docstrings. The following is acceptable in this case:
78
+
- 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_.
66
79
67
80
```python
68
81
def sumab(a, b):
69
82
"""
70
-
This function sums two integers a and b
71
-
Return: a + b
83
+
This function returns the sum of two integers a and b
84
+
Return: a + b
85
+
>>> sum(2, 2)
86
+
4
87
+
>>> sum(-2, 3)
88
+
1
89
+
>>> sum(4.9, 6.1)
90
+
10.0
72
91
"""
73
92
return a + b
74
93
```
75
94
76
-
- `lambda`, `map`, `filter`, `reduce` and complicated list comprehension are welcome and acceptable to demonstrate the power of Python, as long as they are simple enough to read.
77
-
78
-
- This is arguable: **write comments** and assign appropriate variable names, so that the code is easy to read!
79
-
80
-
- Write tests to illustrate your work.
95
+
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:
96
+
```bash
97
+
python3 -m doctest -v my_submission.py
98
+
```
81
99
82
-
The following "testing" approaches are**not** encouraged:
100
+
The use of the Python builtin__input()__ functionis**not** encouraged:
83
101
84
102
```python
85
103
input('Enter your input:')
86
104
# Or even worse...
87
105
input = eval(input("Enter your input: "))
88
106
```
89
107
90
-
However, if your code uses __input()__ then we encourage you to gracefully deal with leading and trailing whitespace in user input by adding __.strip()__ to the end as in:
108
+
However, if your code uses __input()__ then we encourage you to gracefully deal with leading and trailing whitespace in user input by adding __.strip()__ as in:
91
109
92
110
```python
93
111
starting_value = int(input("Please enter a starting value: ").strip())
94
112
```
95
-
96
-
Please write down your test case, like the following:
97
-
98
-
```python
99
-
def sumab(a, b):
100
-
return a + b
101
-
# Write tests this way:
102
-
print(sumab(1, 2)) # 1+2 = 3
103
-
print(sumab(6, 4)) # 6+4 = 10
104
-
# Or this way:
105
-
print("1 + 2 = ", sumab(1, 2)) # 1+2 = 3
106
-
print("6 + 4 = ", sumab(6, 4)) # 6+4 = 10
113
+
114
+
The use of [Python type hints](https://docs.python.org/3/library/typing.html) is encouraged forfunctionparameters and return values. Our automated testing will run [mypy](http://mypy-lang.org) so run that locally before making your submission.
115
+
```python
116
+
def sumab(a: int, b: int) --> int:
117
+
pass
107
118
```
108
119
109
-
Better yet, if you know how to write [__doctests__](https://docs.python.org/3/library/doctest.html), please consider adding them.
120
+
- [__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.
110
121
111
122
- Avoid importing external libraries for basic algorithms. Only use those libraries for complicated algorithms.
112
123
124
+
- 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.
125
+
113
126
#### Other Standard While Submitting Your Work
114
127
115
128
- File extension forcode should be `.py`. Jupiter notebook files are acceptablein machine learning algorithms.
116
129
117
-
- Strictly use snake case (underscore separated) in your file name, as it will be easy to parse in future using scripts.
130
+
- Please avoid creating new directories if at all possible. Try to fit your work into the existing directory structue.
131
+
132
+
- Strictly use snake_case (underscore_separated) in your file_name, as it will be easy to parse in future using scripts.
118
133
119
134
If possible, follow the standard *within* the folder you are submitting to.
120
135
@@ -135,5 +150,4 @@ We want your work to be readable by others; therefore, we encourage you to note
135
150
- Happy coding!
136
151
137
152
138
-
139
153
Writer [@poyea](https://github.com/poyea), Jun 2019.
0 commit comments