contribution guidelines checks (#1787)

* spelling corrections

* review

* improved documentation, removed redundant variables, added testing

* added type hint

* camel case to snake case

* spelling fix

* review

* python --> Python # it is a brand name, not a snake

* explicit cast to int

* spaces in int list

* "!= None" to "is not None"

* Update comb_sort.py

* various spelling corrections in documentation & several variables naming conventions fix

* + char in file name

* import dependency - bug fix

Co-authored-by: John Law <johnlaw.po@gmail.com>

sorts/comb_sort.py

@@ -1,8 +1,13 @@
 """
+This is pure Python implementation of comb sort algorithm.
 Comb sort is a relatively simple sorting algorithm originally designed by Wlodzimierz Dobosiewicz in 1980.
-Later it was rediscovered by Stephen Lacey and Richard Box in 1991. Comb sort improves on bubble sort.
+It was rediscovered by Stephen Lacey and Richard Box in 1991. Comb sort improves on bubble sort algorithm.
+In bubble sort, distance (or gap) between two compared elements is always one.
+Comb sort improvement is that gap can be much more than 1, in order to prevent slowing down by small values
+at the end of a list.
+
+More info on: https://en.wikipedia.org/wiki/Comb_sort
 
-This is pure python implementation of comb sort algorithm
 For doctests run following command:
 python -m doctest -v comb_sort.py
 or
@@ -13,42 +18,44 @@ python comb_sort.py
 """
 
 
-def comb_sort(data):
+def comb_sort(data: list) -> list:
     """Pure implementation of comb sort algorithm in Python
-    :param collection: some mutable ordered collection with heterogeneous
-    comparable items inside
-    :return: the same collection ordered by ascending
+    :param data: mutable collection with comparable items
+    :return: the same collection in ascending order
     Examples:
     >>> comb_sort([0, 5, 3, 2, 2])
     [0, 2, 2, 3, 5]
     >>> comb_sort([])
     []
-    >>> comb_sort([-2, -5, -45])
-    [-45, -5, -2]
+    >>> comb_sort([99, 45, -7, 8, 2, 0, -15, 3])
+    [-15, -7, 0, 2, 3, 8, 45, 99]
     """
     shrink_factor = 1.3
     gap = len(data)
-    swapped = True
-    i = 0
+    completed = False
+
+    while not completed:
 
-    while gap > 1 or swapped:
         # Update the gap value for a next comb
-        gap = int(float(gap) / shrink_factor)
+        gap = int(gap / shrink_factor)
+        if gap <= 1:
+            completed = True
 
-        swapped = False
-        i = 0
-
-        while gap + i < len(data):
-            if data[i] > data[i + gap]:
+        index = 0
+        while index + gap < len(data):
+            if data[index] > data[index + gap]:
                 # Swap values
-                data[i], data[i + gap] = data[i + gap], data[i]
-                swapped = True
-            i += 1
+                data[index], data[index + gap] = data[index + gap], data[index]
+                completed = False
+            index += 1
 
     return data
 
 
 if __name__ == "__main__":
+    import doctest
+    doctest.testmod()
+
     user_input = input("Enter numbers separated by a comma:\n").strip()
     unsorted = [int(item) for item in user_input.split(",")]
     print(comb_sort(unsorted))