|
| 1 | +# Contributing guidelines |
| 2 | + |
| 3 | +Welcome to [TheAlgorithms/Nim](https://github.com/TheAlgorithms/Nim)! Before you send your pull requests, please make sure that you **read the whole guidelines**. If you have any doubt about the contributing guide, please feel free to [state it clearly in an issue](https://github.com/TheAlgorithms/Nim/issues/new) or ask the community in [Discord](https://the-algorithms.com/discord). |
| 4 | + |
| 5 | +## Contributing |
| 6 | + |
| 7 | +We are very happy that you are considering implementing algorithms and data structures for others!\ |
| 8 | +This repository is referenced and used by learners from all over the globe. Being one of our contributors, you agree and confirm that: |
| 9 | + |
| 10 | +- You did your work - no plagiarism allowed |
| 11 | + - Any plagiarized work will not be merged. |
| 12 | +- Your work will be distributed under [MIT License](LICENSE.md) once your pull request is merged |
| 13 | +- Your submitted work fulfills our styles and standards |
| 14 | + |
| 15 | +**New implementations** are welcome! For example, new solutions for a problem, different representations for a graph data structure, or algorithm designs with different complexity but **identical implementation** of an existing implementation is not allowed. Please check whether the solution is already implemented or not before submitting your pull request. |
| 16 | + |
| 17 | +**Improving comments** and **writing proper tests** are also highly welcome. |
| 18 | + |
| 19 | +### Contribution |
| 20 | + |
| 21 | +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. |
| 22 | + |
| 23 | +Please help us keep our issue list small by adding fixes: Add the number of the issue you solved — even if only partially — to the commit message of your pull request. GitHub will use this tag to auto-close the issue when the PR is merged. |
| 24 | + |
| 25 | +#### What is an Algorithm? |
| 26 | + |
| 27 | +An Algorithm is one or more functions (or classes) that: |
| 28 | + |
| 29 | +* take one or more inputs, |
| 30 | +* perform some internal calculations or data manipulations, |
| 31 | +* return one or more outputs, |
| 32 | +* have minimal side effects (Examples of side effects: `echo()`, `rand()`, `read()`, `write()`). |
| 33 | + |
| 34 | +Algorithms should be packaged in a way that would make it easy for readers to put them into larger programs. |
| 35 | + |
| 36 | +Algorithms should: |
| 37 | + |
| 38 | +* have intuitive object and function names that make their purpose clear to readers |
| 39 | +* use Nim naming conventions and intuitive variable names with correct typing to ease comprehension |
| 40 | +* Don't use unsigned numerical types (`uint` and its sized variants), unless wrapping behaviour or binary manipulation is required for the algorithm. |
| 41 | +* raise Nim exceptions (`ValueError`, etc.) on erroneous input values |
| 42 | +* The side effects must be annotated |
| 43 | +* have documentation comments with clear explanations and/or URLs to source materials |
| 44 | +* contain tests (runnableExamples, std/unittest) that test both valid and erroneous input values |
| 45 | +* return all calculation results instead of printing or plotting them |
| 46 | + |
| 47 | +Please focus hard on the naming of functions, objects, and variables. Help your reader by using **descriptive names** that can help you to remove redundant comments. |
| 48 | + - Single letter variable names must be avoided unless your variable has a short lifespan. If your variable come from a mathematical context, no confusion is possible with another variable, you may use single-letter variables. When there are multiple indices (matrix, sums integrals) you may use single-letter variables. For string algorithms, `c` for character is a common use. Pay attention though not creating any confusion when dealing with multiple characters. |
| 49 | + You can use `index` instead of `i` when iterating in a `for` loop. |
| 50 | + - For some parameters, using short variable names enable to distinguish the inputs easily from the parameters. |
| 51 | + - Expand acronyms. Prefer `greatestCommonDivisor()` to `gcd()`, as the former is easier to understand than the latter, especially for non-native English speakers. |
| 52 | + - The variable and function names should be camelCase while object names should be PascalCase. |
| 53 | +- Pay attention to spacing around operators. |
| 54 | +- Avoid importing external libraries for basic algorithms. Only use those libraries for complicated algorithms. |
| 55 | + |
| 56 | +Algorithms in this repo should not be how-to examples for existing Nim packages. Instead, they should perform internal calculations or manipulations to convert input values into different output values. Those calculations or manipulations can use objects or functions of existing Nim modules but each algorithm in this repo should add unique value. |
| 57 | + |
| 58 | +#### Nim Coding Style |
| 59 | + |
| 60 | +We want your work to be readable by others; therefore, we encourage you to follow the [Nim Coding Style](https://nim-lang.org/docs/nep1.html) that is enforced in the Nim compiler and Standard Library. |
| 61 | + |
| 62 | +We also enforce some additional rules: |
| 63 | + |
| 64 | +- Please compile using the stable version of the Nim compiler. The 2.0 version is not out as we wrote these lines but you can compile against the pre-release version of the compiler: [https://nim-lang.org/blog/2022/12/21/version-20-rc.html]. |
| 65 | +- Prefer `Natural`, `Positive` or custom [subrange types](https://nim-lang.org/docs/manual.html#types-subrange-types) to unconstrained `int` where applicable, use `Natural` for indexing. |
| 66 | +- Add the title of your algorithm (in Camel Case) with a comment on the top of your file |
| 67 | +- Right under the title, add a `{.push raises: [].}`. This enforces that by default all `func`s have an empty list of exceptions. If they do raise at least an exception, then write after the return type and before the `=` sign, the list of exceptions raised in a similar pragma: `{.raises: [IOError].}`. |
| 68 | +- If you need a third-party module that is not in the file [third_party_modules.md](https://github.com/TheAlgorithms/Nim/blob/master/third_party_modules.md), please add it to that file as part of your submission. |
| 69 | +- If you are searching for the equivalent of `NULL` (default value for pointers), you might look for [`std/options`](https://nim-lang.org/docs/options.html) instead. |
| 70 | +Using the specific `Option[T]` generic type adds compile-time checks. |
| 71 | +If you are wondering why we prefer to avoid Null references, you should check [Tony Hoare's conference at QCon 2009](https://www.infoq.com/presentations/Null-References-The-Billion-Dollar-Mistake-Tony-Hoare/). |
| 72 | +- For your code to be integrated in larger modules, we recommend using a `when isMainModule` clause to run tests and examples. |
| 73 | +- It is incited to give a usage example under a top-level `runnableExamples` on top of the file (under the title and the `push raises` pragma). |
| 74 | +- You are not enforced to use the export marker `*`. It is preferable to use it in order to distinguish helper functions with internal details and the functions of your [application programming interface (API)](https://en.wikipedia.org/wiki/API) for the end user. |
| 75 | +- You can use the `std/unittest` module from the standard library to test your program. Below is a sample of code. |
| 76 | + |
| 77 | +```nim |
| 78 | +#My Algorithm |
| 79 | +{.push raises: [].} |
| 80 | +
|
| 81 | +runnableExamples: |
| 82 | + echo myFunction("bla") |
| 83 | +
|
| 84 | +func myFunction(s: string): string {.raises: [ValueError].} = |
| 85 | + if s.len == 0: |
| 86 | + raise newException(ValueError, "Empty string") |
| 87 | + return s |
| 88 | +
|
| 89 | +when isMainModule: |
| 90 | + import std/unittest |
| 91 | +
|
| 92 | + suite "A suite of tests": |
| 93 | + test "runs correctly": |
| 94 | + check myFunction("bla") == "bla" |
| 95 | + test "raises ValueError": |
| 96 | + expect(ValueError): discard myFunction("") |
| 97 | +
|
| 98 | +``` |
| 99 | + |
| 100 | +#### Submissions Requirements |
| 101 | + |
| 102 | +- The file extension for algorithm files should be `.nim`. |
| 103 | +- Look up if the name of your algorithm already exists in another repository of [TheAlgorithms](https://github.com/TheAlgorithms/) like [TheAlgorithms/Python](https://github.com/TheAlgorithms/Python). By reusing the same name, your implementation will be regrouped with implementations of other languages. |
| 104 | +- Strictly use snake_case (underscore_separated) in your file_name, as it will be easy to parse in future using scripts. |
| 105 | +- Please open an issue first if you want to create a new directory. Try to fit your work into the existing directory structure as much as possible. |
| 106 | +- If possible, follow the standard *within* the folder you are submitting to. |
| 107 | +- If you have modified/added code work, make sure the code compiles before submitting. Please precise the version of the compiler you used in your Pull Request. |
| 108 | +- If you have modified/added documentation work, ensure your language is concise and contains no grammar errors. |
| 109 | +- Add a corresponding explanation to [Algorithms-Explanation](https://github.com/TheAlgorithms/Algorithms-Explanation) (Optional but recommended). |
| 110 | + |
| 111 | +- Most importantly, |
| 112 | + - **Be consistent in the use of these guidelines when submitting.** |
| 113 | + - **Join** us on [Discord](https://the-algorithms.com/discord) **now!** |
| 114 | + - Happy coding! |
| 115 | + |
| 116 | +Writer [@dlesnoff](https://github.com/dlesnoff), Mar 2023. |
0 commit comments