backup/C-Plus-Plus
1
0
Fork 0
mirror of https://github.com/TheAlgorithms/C-Plus-Plus.git synced 2026-07-11 22:46:11 +08:00
Code Issues Projects Releases Wiki Activity

Documentation for 341ed50da8

Browse Source
This commit is contained in:
github-actions
2021-09-03 19:56:17 +00:00
parent 52d0c55145
commit 08e8eb037e
3432 changed files with 71392 additions and 72953 deletions
Download Patch File Download Diff File Expand all files Collapse all files

438
d6/dcd/md__c_o_n_t_r_i_b_u_t_i_n_g.html
View File

@@ -2,8 +2,8 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.2"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Algorithms_in_C++: CONTRIBUTION GUIDELINES</title>
<link href="../../tabs.css" rel="stylesheet" type="text/css"/>
@@ -17,9 +17,9 @@
<script type="text/javascript" src="../../search/searchdata.js"></script>
<script type="text/javascript" src="../../search/search.js"></script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
extensions: ["tex2jax.js", "TeX/AMSmath.js", "TeX/AMSsymbols.js"],
jax: ["input/TeX","output/HTML-CSS"],
MathJax.Hub.Config({
extensions: ["tex2jax.js", "TeX/AMSmath.js", "TeX/AMSsymbols.js"],
jax: ["input/TeX","output/HTML-CSS"],
});
</script>
<script type="text/javascript" async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-MML-AM_CHTML/MathJax.js"></script>
@@ -32,8 +32,7 @@
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Algorithms_in_C++
&#160;<span id="projectnumber">1.0.0</span>
<div id="projectname">Algorithms_in_C++<span id="projectnumber">&#160;1.0.0</span>
</div>
<div id="projectbrief">Set of algorithms implemented in C++.</div>
</td>
@@ -42,21 +41,22 @@
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<!-- Generated by Doxygen 1.9.2 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "../../search",false,'Search','.html');
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "../../search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="../../menudata.js"></script>
<script type="text/javascript" src="../../menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('../../',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
@@ -70,7 +70,7 @@ $(function() {
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('d6/dcd/md__c_o_n_t_r_i_b_u_t_i_n_g.html','../../'); initResizable(); });
/* @license-end */
</script>
@@ -89,228 +89,238 @@ $(document).ready(function(){initNavTree('d6/dcd/md__c_o_n_t_r_i_b_u_t_i_n_g.htm
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">CONTRIBUTION GUIDELINES </div> </div>
<div><div class="header">
<div class="headertitle"><div class="title">CONTRIBUTION GUIDELINES </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="autotoc_md16"></a>
Before contributing</h1>
<p>Welcome to <a href="https://github.com/TheAlgorithms/C-Plus-Plus">TheAlgorithms/C-Plus-Plus</a>! Before submitting pull requests, please make sure that you have <b>read the whole guidelines</b>. If you have any doubts about this contribution guide, please open <a href="https://github.com/TheAlgorithms/C-Plus-Plus/issues/new/choose">an issue</a> or ask in our <a href="https://discord.gg/c7MnfGFGa6">Discord server</a>, and clearly state your concerns.</p>
<p >Welcome to <a href="https://github.com/TheAlgorithms/C-Plus-Plus" target="_blank">TheAlgorithms/C-Plus-Plus</a>! Before submitting pull requests, please make sure that you have <b>read the whole guidelines</b>. If you have any doubts about this contribution guide, please open <a href="https://github.com/TheAlgorithms/C-Plus-Plus/issues/new/choose" target="_blank">an issue</a> or ask in our <a href="https://discord.gg/c7MnfGFGa6" target="_blank">Discord server</a>, and clearly state your concerns.</p>
<h1><a class="anchor" id="autotoc_md17"></a>
Contributing</h1>
<h2><a class="anchor" id="autotoc_md18"></a>
Maintainer/reviewer</h2>
<p><b>Please check the <a href="https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/REVIEWER_CODE.md">reviewer code</a> file for maintainers and reviewers.</b></p>
<p ><b>Please check the <a href="https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/REVIEWER_CODE.md" target="_blank">reviewer code</a> file for maintainers and reviewers.</b></p>
<h2><a class="anchor" id="autotoc_md19"></a>
Contributor</h2>
<p>Being a contributor at The Algorithms, we request you to follow the points mentioned below:</p>
<p >Being a contributor at The Algorithms, we request you to follow the points mentioned below:</p>
<ul>
<li>You did your own work.<ul>
<li>No plagiarism allowed. Any plagiarized work will not be merged.</li>
</ul>
</li>
<li>Your work will be distributed under the <a href="https://github.com/TheAlgoritms/C-Plus-Plus/blob/master/LICENSE">MIT License</a> once your pull request has been merged.</li>
<li>Your work will be distributed under the <a href="https://github.com/TheAlgoritms/C-Plus-Plus/blob/master/LICENSE" target="_blank">MIT License</a> once your pull request has been merged.</li>
<li>Please follow the repository guidelines and standards mentioned below.</li>
</ul>
<p><b>New implementation</b> New implementations are welcome!</p>
<p>You can add new algorithms or data structures which are <b>not present in the repository</b> or that can <b>improve</b> the old implementations (<b>documentation</b>, <b>improving test cases</b>, removing bugs or in any other resonable sense)</p>
<p><b>Issues</b> Please avoid opening issues asking to be "assigned” to a particular algorithm. This merely creates unnecessary noise for maintainers. Instead, please submit your implementation in a pull request, and it will be evaluated by project maintainers.</p>
<h2><a class="anchor" id="autotoc_md20"></a>
Making Changes</h2>
<h3><a class="anchor" id="autotoc_md21"></a>
Code</h3>
<ul>
<li>Please use the directory structure of the repository.</li>
<li>Make sure the file extensions should be <code>*.hpp</code>, <code>*.h</code> or <code>*.cpp</code>.</li>
<li>Don't use **<code>bits/stdc++.h</code>** because this is quite Linux-specific and slows down the compilation process.</li>
<li>Organize your code using **<code>struct</code>**, **<code>class</code>**, and/or **<code>namespace</code>** keywords</li>
<li>If an implementation of the algorithm already exists, please refer to the <a href="../../#new-file-name-guidelines">file-name section below</a>.</li>
<li>You can suggest reasonable changes to existing algorithms.</li>
<li>Strictly use snake_case (underscore_separated) in filenames.</li>
<li>If you have added or modified code, please make sure the code compiles before submitting.</li>
<li>Our automated testing runs <a href="https://cmake.org/"><b>CMake</b></a> on all the pull requests, so please be sure that your code passes before submitting.</li>
<li>Please conform to <a href="https://www.doxygen.nl/manual/docblocks.html">Doxygen</a> standard and document the code as much as possible. This not only facilitates the readers but also generates the correct info on the website.</li>
<li><b>Be consistent in the use of these guidelines.</b></li>
</ul>
<h3><a class="anchor" id="autotoc_md22"></a>
Documentation</h3>
<ul>
<li>Make sure you put useful comments in your code. Do not comment on obvious things.</li>
<li>Please avoid creating new directories if at all possible. Try to fit your work into the existing directory structure. If you want to create a new directory, then please check if a similar category has been recently suggested or created by other pull requests.</li>
<li>If you have modified/added documentation, please ensure that your language is concise and must not contain grammatical errors.</li>
<li>Do not update <a href="https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/README.md"><code>README.md</code></a> along with other changes. First, create an issue and then link to that issue in your pull request to suggest specific changes required to <a href="https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/README.md"><code>README.md</code></a>.</li>
<li>The repository follows <a href="https://www.doxygen.nl/manual/docblocks.html">Doxygen</a> standards and auto-generates the <a href="https://thealgorithms.github.io/C-Plus-Plus">repository website</a>. Please ensure the code is documented in this structure. A sample implementation is given below.</li>
</ul>
<h3><a class="anchor" id="autotoc_md23"></a>
Test</h3>
<ul>
<li>Make sure to add examples and test cases in your <code><a class="el" href="../../d3/d40/graph__coloring_8cpp.html#gae66f6b31b5ad750f1fe042a706a4e3d4">main()</a></code> function.</li>
<li>If you find an algorithm or document without tests, please feel free to create a pull request or issue describing suggested changes.</li>
<li>Please try to add one or more <code><a class="el" href="../../dc/d5a/rat__maze_8cpp.html#aa8dca7b867074164d5f45b0f3851269d" title="Test implementations.">test()</a></code> functions that will invoke the algorithm implementation on random test data with the expected output. Use the <code>assert()</code> function to confirm that the tests will pass. Requires including the <code>cassert</code> library.</li>
</ul>
<h3><a class="anchor" id="autotoc_md24"></a>
Typical structure of a program</h3>
<div class="fragment"><div class="line"><span class="comment">/**</span></div>
<div class="line"><span class="comment"> * @file</span></div>
<div class="line"><span class="comment"> * @brief Add one line description here</span></div>
<div class="line"><span class="comment"> * @details</span></div>
<div class="line"><span class="comment"> * This is a multi-line</span></div>
<div class="line"><span class="comment"> * description containing links, references,</span></div>
<div class="line"><span class="comment"> * math equations, etc.</span></div>
<div class="line"><span class="comment"> * @author [Name](https://github.com/handle)</span></div>
<div class="line"><span class="comment"> * @see related_file.cpp, another_file.cpp</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"> </div>
<div class="line"><span class="preprocessor">#include &lt;cassert&gt;</span> <span class="comment">/// for assert</span></div>
<div class="line"><span class="preprocessor">#include </span><span class="comment">/// for `some function here`</span></div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment">/**</span></div>
<div class="line"><span class="comment"> * @namespace &lt;check from other files in this repo&gt;</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"><span class="keyword">namespace </span>name {</div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment">/**</span></div>
<div class="line"><span class="comment"> * @brief Class documentation</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"><span class="keyword">class </span>class_name {</div>
<div class="line"> <span class="keyword">private</span>:</div>
<div class="line"> <span class="keywordtype">int</span> variable; <span class="comment">///&lt; short info of this variable</span></div>
<div class="line"> <span class="keywordtype">char</span> *message; <span class="comment">///&lt; short info</span></div>
<div class="line"> </div>
<div class="line"> <span class="keyword">public</span>:</div>
<div class="line"> <span class="comment">// other members also documented as below</span></div>
<div class="line">}</div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment">/**</span></div>
<div class="line"><span class="comment"> * @brief Function documentation</span></div>
<div class="line"><span class="comment"> * @tparam T this is a one-line info about T</span></div>
<div class="line"><span class="comment"> * @param param1 on-line info about param1</span></div>
<div class="line"><span class="comment"> * @param param2 on-line info about param2</span></div>
<div class="line"><span class="comment"> * @returns `true` if ...</span></div>
<div class="line"><span class="comment"> * @returns `false` if ...</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"><span class="keyword">template</span>&lt;<span class="keyword">class</span> T&gt;</div>
<div class="line"><span class="keywordtype">bool</span> func(<span class="keywordtype">int</span> param1, T param2) {</div>
<div class="line"> <span class="comment">// function statements here</span></div>
<div class="line"> <span class="keywordflow">if</span> (<span class="comment">/*something bad*/</span>) {</div>
<div class="line"> <span class="keywordflow">return</span> <span class="keyword">false</span>;</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
<div class="line">}</div>
<div class="line">} <span class="comment">// namespace name</span></div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment">/**</span></div>
<div class="line"><span class="comment"> * @brief Self-test implementations</span></div>
<div class="line"><span class="comment"> * @returns void</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"><span class="keyword">static</span> <span class="keywordtype">void</span> <a class="code" href="../../dc/d5a/rat__maze_8cpp.html#aa8dca7b867074164d5f45b0f3851269d">test</a>() {</div>
<div class="line"> <span class="comment">/* descriptions of the following test */</span></div>
<div class="line"> assert(func(...) == ...); <span class="comment">// this ensures that the algorithm works as expected</span></div>
<div class="line"> </div>
<div class="line"> <span class="comment">// can have multiple checks</span></div>
<div class="line">}</div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment">/**</span></div>
<div class="line"><span class="comment"> * @brief Main function</span></div>
<div class="line"><span class="comment"> * @param argc commandline argument count (ignored)</span></div>
<div class="line"><span class="comment"> * @param argv commandline array of arguments (ignored)</span></div>
<div class="line"><span class="comment"> * @returns 0 on exit</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"><span class="keywordtype">int</span> <a class="code" href="../../d3/d40/graph__coloring_8cpp.html#gae66f6b31b5ad750f1fe042a706a4e3d4">main</a>(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> *argv[]) {</div>
<div class="line"> <a class="code" href="../../dc/d5a/rat__maze_8cpp.html#aa8dca7b867074164d5f45b0f3851269d">test</a>(); <span class="comment">// run self-test implementations</span></div>
<div class="line"> <span class="comment">// code here</span></div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
<div class="ttc" id="agraph__coloring_8cpp_html_gae66f6b31b5ad750f1fe042a706a4e3d4"><div class="ttname"><a href="../../d3/d40/graph__coloring_8cpp.html#gae66f6b31b5ad750f1fe042a706a4e3d4">main</a></div><div class="ttdeci">int main()</div><div class="ttdef"><b>Definition:</b> graph_coloring.cpp:100</div></div>
<div class="ttc" id="arat__maze_8cpp_html_aa8dca7b867074164d5f45b0f3851269d"><div class="ttname"><a href="../../dc/d5a/rat__maze_8cpp.html#aa8dca7b867074164d5f45b0f3851269d">test</a></div><div class="ttdeci">static void test()</div><div class="ttdoc">Test implementations.</div><div class="ttdef"><b>Definition:</b> rat_maze.cpp:84</div></div>
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md25"></a>
New File Name guidelines</h3>
<ul>
<li>Use lowercase words with <code>"_"</code> as a separator</li>
<li>For instance</li>
</ul>
<div class="fragment"><div class="line">MyNewCppClass.CPP is incorrect</div>
<div class="line">my_new_cpp_class.cpp is correct format</div>
</div><!-- fragment --><ul>
<li>It will be used to dynamically create a directory of files and implementation.</li>
<li>File name validation will run on Docker to ensure validity.</li>
<li>If an implementation of the algorithm already exists and your version is different from that implemented, please use incremental numeric digit as a suffix. For example: if <code><a class="el" href="../../d9/d69/median__search_8cpp.html" title="Implementation of Median search algorithm. @cases from here">median_search.cpp</a></code> already exists in the <code>search</code> folder, and you are contributing a new implementation, the filename should be <code>median_search2.cpp</code> and for a third implementation, <code>median_search3.cpp</code>.</li>
</ul>
<h3><a class="anchor" id="autotoc_md26"></a>
New Directory guidelines</h3>
<ul>
<li>We recommend adding files to existing directories as much as possible.</li>
<li>Use lowercase words with <code>"_"</code> as separator ( no spaces or <code>"-"</code> allowed )</li>
<li>For instance</li>
</ul>
<div class="fragment"><div class="line">SomeNew Fancy-Category is incorrect</div>
<div class="line">some_new_fancy_category is correct</div>
</div><!-- fragment --><ul>
<li>Filepaths will be used to dynamically create a directory of our algorithms.</li>
<li>Filepath validation will run on GitHub Actions to ensure compliance.</li>
</ul>
<h3><a class="anchor" id="autotoc_md27"></a>
Commit Guidelines</h3>
<ul>
<li>It is recommended to keep your changes grouped logically within individual commits. Maintainers find it easier to understand changes that are logically spilled across multiple commits. Try to modify just one or two files in the same directory. Pull requests that span multiple directories are often rejected.</li>
</ul>
<div class="fragment"><div class="line">git add file_xyz.cpp</div>
<div class="line">git commit -m &quot;your message&quot;</div>
</div><!-- fragment --><p>Examples of commit messages with semantic prefixes:</p>
<div class="fragment"><div class="line">fix: xyz algorithm bug</div>
<div class="line">feat: add xyx algorithm, class xyz</div>
<div class="line">test: add test for xyz algorithm</div>
<div class="line">docs: add comments and explanation to xyz algorithm</div>
</div><!-- fragment --><p>Common prefixes:</p>
<ul>
<li>fix: A bug fix</li>
<li>feat: A new feature</li>
<li>docs: Documentation changes</li>
<li>test: Correct existing tests or add new ones</li>
</ul>
<h2><a class="anchor" id="autotoc_md28"></a>
Pull Requests</h2>
<ul>
<li>Checkout our <a href="https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/.github/pull_request_template.md">pull request template</a></li>
</ul>
<h3><a class="anchor" id="autotoc_md29"></a>
Building Locally</h3>
<p>Before submitting a pull request, build the code locally or using the convenient <a href="https://gitpod.io/#https://github.com/TheAlgorithms/C-Plus-Plus"><img src="https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod" alt="Gitpod Ready-to-Code" class="inline"/></a> service.</p>
<div class="fragment"><div class="line">cmake -B build -S .</div>
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md30"></a>
Static Code Analyzer</h3>
<p>We use <a href="https://clang.llvm.org/extra/clang-tidy/"><code>clang-tidy</code></a> as a static code analyzer with a configuration in <a href="https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/.clang-tidy"><code>.clang-tidy</code></a>.</p>
<div class="fragment"><div class="line">clang-tidy --fix --quiet -p build subfolder/file_to_check.cpp --</div>
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md31"></a>
Code Formatter</h3>
<p><a href="https://clang.llvm.org/docs/ClangFormat.html"><code>__clang-format__</code></a> is used for code forrmating.</p>
<ul>
<li>Installation (only needs to be installed once.)<ul>
<li>Mac (using home-brew): <code>brew install clang-format</code></li>
<li>Mac (using macports): <code>sudo port install clang-10 +analyzer</code></li>
<li>Windows (MSYS2 64-bit): <code>pacman -S mingw-w64-x86_64-clang-tools-extra</code></li>
<li>Linux (Debian): <code>sudo apt-get install clang-format-10 clang-tidy-10</code></li>
</ul>
</li>
<li>Running (all platforms): <code>clang-format -i -style="file" my_file.cpp</code></li>
</ul>
<h3><a class="anchor" id="autotoc_md32"></a>
GitHub Actions</h3>
<ul>
<li>Enable GitHub Actions on your fork of the repository. After enabling, it will execute <code>clang-tidy</code> and <code>clang-format</code> after every push (not a commit).<ul>
<li>Click on the tab "Actions", then click on the big green button to enable it.</li>
</ul>
</li>
</ul>
<p><img src="https://user-images.githubusercontent.com/51391473/94609466-6e925100-0264-11eb-9d6f-3706190eab2b.png" alt="GitHub Actions" class="inline"/></p>
<p ><b>New implementation</b> New implementations are welcome!</p>
<p >You can add new algorithms or data structures which are <b>not present in the repository</b> or that can <b>improve</b> the old implementations (<b>documentation</b>, <b>improving test cases</b>, removing bugs or in any other resonable sense)</p>
<p ><b>Issues</b> Please avoid opening issues asking to be "assigned” to a particular algorithm. This merely creates unnecessary noise for maintainers. Instead, please submit your implementation in a pull request, and it will be evaluated by project maintainers.
@subsection autotoc_md20 Making Changes
@subsubsection autotoc_md21 Code
- Please use the directory structure of the repository.
- Make sure the file extensions should be &lt;tt&gt;*.hpp&lt;/tt&gt;, &lt;tt&gt;*.h&lt;/tt&gt; or &lt;tt&gt;*.cpp&lt;/tt&gt;.
- Don't use **&lt;tt&gt;bits/stdc++.h&lt;/tt&gt;** because this is quite Linux-specific and slows down the compilation process.
- Organize your code using **&lt;tt&gt;struct&lt;/tt&gt;**, **&lt;tt&gt;class&lt;/tt&gt;**, and/or **&lt;tt&gt;namespace&lt;/tt&gt;** keywords
- If an implementation of the algorithm already exists, please refer to the &lt;a href="#new-file-name-guidelines" target="_blank" &gt;file-name section below&lt;/a&gt;.
- You can suggest reasonable changes to existing algorithms.
- Strictly use snake_case (underscore_separated) in filenames.
- If you have added or modified code, please make sure the code compiles before submitting.
- Our automated testing runs &lt;a href="<a href="https://cmake.org/">https://cmake.org/</a>" target="_blank" &gt;&lt;strong&gt;CMake&lt;/strong&gt;&lt;/a&gt; on all the pull requests, so please be sure that your code passes before submitting.
- Please conform to &lt;a href="<a href="https://www.doxygen.nl/manual/docblocks.html">https://www.doxygen.nl/manual/docblocks.html</a>" target="_blank" &gt;Doxygen&lt;/a&gt; standard and document the code as much as possible. This not only facilitates the readers but also generates the correct info on the website.
- &lt;strong&gt;Be consistent in the use of these guidelines.&lt;/strong&gt;
@subsubsection autotoc_md22 Documentation
- Make sure you put useful comments in your code. Do not comment on obvious things.
- Please avoid creating new directories if at all possible. Try to fit your work into the existing directory structure. If you want to create a new directory, then please check if a similar category has been recently suggested or created by other pull requests.
- If you have modified/added documentation, please ensure that your language is concise and must not contain grammatical errors.
- Do not update &lt;a href="<a href="https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/README.md">https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/README.md</a>" target="_blank" &gt;&lt;tt&gt;README.md&lt;/tt&gt;&lt;/a&gt; along with other changes. First, create an issue and then link to that issue in your pull request to suggest specific changes required to &lt;a href="<a href="https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/README.md">https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/README.md</a>" target="_blank" &gt;&lt;tt&gt;README.md&lt;/tt&gt;&lt;/a&gt;.
- The repository follows &lt;a href="<a href="https://www.doxygen.nl/manual/docblocks.html">https://www.doxygen.nl/manual/docblocks.html</a>" target="_blank" &gt;Doxygen&lt;/a&gt; standards and auto-generates the &lt;a href="<a href="https://thealgorithms.github.io/C-Plus-Plus">https://thealgorithms.github.io/C-Plus-Plus</a>" target="_blank" &gt;repository website&lt;/a&gt;. Please ensure the code is documented in this structure. A sample implementation is given below.
@subsubsection autotoc_md23 Test
- Make sure to add examples and test cases in your &lt;tt&gt;main()&lt;/tt&gt; function.
- If you find an algorithm or document without tests, please feel free to create a pull request or issue describing suggested changes.
- Please try to add one or more &lt;tt&gt;test()&lt;/tt&gt; functions that will invoke the algorithm implementation on random test data with the expected output. Use the &lt;tt&gt;assert()&lt;/tt&gt; function to confirm that the tests will pass. Requires including the &lt;tt&gt;cassert&lt;/tt&gt; library.
@subsubsection autotoc_md24 Typical structure of a program
@code{cpp}
/**
* @file
* @brief Add one line description here
* @details
* This is a multi-line
* description containing links, references,
* math equations, etc.
* @author [Name](https://github.com/handle)
* @see related_file.cpp, another_file.cpp
*/
#include &lt;cassert&gt; /// for assert
#include /// for `some function here`
/**
* @namespace &lt;check from other files in this repo&gt;
*/
namespace name {
/**
* @brief Class documentation
*/
class class_name {
private:
int variable; ///&lt; short info of this variable
char *message; ///&lt; short info
public:
// other members also documented as below
}
/**
* @brief Function documentation
* @tparam T this is a one-line info about T
* @param param1 on-line info about param1
* @param param2 on-line info about param2
* @returns `true` if ...
* @returns `false` if ...
*/
template&lt;class T&gt;
bool func(int param1, T param2) {
// function statements here
if (/*something bad*/) {
return false;
}
return true;
}
} // namespace name
/**
* @brief Self-test implementations
* @returns void
*/
static void test() {
/* descriptions of the following test */
assert(func(...) == ...); // this ensures that the algorithm works as expected
// can have multiple checks
}
/**
* @brief Main function
* @param argc commandline argument count (ignored)
* @param argv commandline array of arguments (ignored)
* @returns 0 on exit
*/
int main(int argc, char *argv[]) {
test(); // run self-test implementations
// code here
return 0;
}
@endcode
@subsubsection autotoc_md25 New File Name guidelines
- Use lowercase words with &lt;tt&gt;"_"&lt;/tt&gt; as a separator
- For instance
@code{markdown}
MyNewCppClass.CPP is incorrect
my_new_cpp_class.cpp is correct format
@endcode
- It will be used to dynamically create a directory of files and implementation.
- File name validation will run on Docker to ensure validity.
- If an implementation of the algorithm already exists and your version is different from that implemented, please use incremental numeric digit as a suffix. For example: if &lt;tt&gt;median_search.cpp&lt;/tt&gt; already exists in the &lt;tt&gt;search&lt;/tt&gt; folder, and you are contributing a new implementation, the filename should be &lt;tt&gt;median_search2.cpp&lt;/tt&gt; and for a third implementation, &lt;tt&gt;median_search3.cpp&lt;/tt&gt;.
@subsubsection autotoc_md26 New Directory guidelines
- We recommend adding files to existing directories as much as possible.
- Use lowercase words with &lt;tt&gt;"_"&lt;/tt&gt; as separator ( no spaces or &lt;tt&gt;"-"&lt;/tt&gt; allowed )
- For instance
@code{markdown}
SomeNew Fancy-Category is incorrect
some_new_fancy_category is correct
@endcode
- Filepaths will be used to dynamically create a directory of our algorithms.
- Filepath validation will run on GitHub Actions to ensure compliance.
@subsubsection autotoc_md27 Commit Guidelines
- It is recommended to keep your changes grouped logically within individual commits. Maintainers find it easier to understand changes that are logically spilled across multiple commits. Try to modify just one or two files in the same directory. Pull requests that span multiple directories are often rejected.
@code{bash}
git add file_xyz.cpp
git commit -m "your message"
@endcode
Examples of commit messages with semantic prefixes:
@code{markdown}
fix: xyz algorithm bug
feat: add xyx algorithm, class xyz
test: add test for xyz algorithm
docs: add comments and explanation to xyz algorithm
@endcode
Common prefixes:
- fix: A bug fix
- feat: A new feature
- docs: Documentation changes
- test: Correct existing tests or add new ones
@subsection autotoc_md28 Pull Requests
- Checkout our &lt;a href="<a href="https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/.github/pull_request_template.md">https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/.github/pull_request_template.md</a>" target="_blank" &gt;pull request template&lt;/a&gt;
@subsubsection autotoc_md29 Building Locally
Before submitting a pull request,
build the code locally or using the convenient &lt;a href="<a href="https://gitpod.io/#https://github.com/TheAlgorithms/C-Plus-Plus">https://gitpod.io/#https://github.com/TheAlgorithms/C-Plus-Plus</a>" target="_blank" &gt;&lt;img src="<a href="https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod">https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod</a>" alt="Gitpod Ready-to-Code"/&gt;&lt;/a&gt; service.
@code{bash}
cmake -B build -S .
@endcode
@subsubsection autotoc_md30 Static Code Analyzer
We use &lt;a href="<a href="https://clang.llvm.org/extra/clang-tidy/">https://clang.llvm.org/extra/clang-tidy/</a>" target="_blank" &gt;&lt;tt&gt;clang-tidy&lt;/tt&gt;&lt;/a&gt; as a static code analyzer with a configuration in &lt;a href="<a href="https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/.clang-tidy">https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/.clang-tidy</a>" target="_blank" &gt;&lt;tt&gt;.clang-tidy&lt;/tt&gt;&lt;/a&gt;.
@code{bash}
clang-tidy --fix --quiet -p build subfolder/file_to_check.cpp --
@endcode
@subsubsection autotoc_md31 Code Formatter
&lt;a href="<a href="https://clang.llvm.org/docs/ClangFormat.html">https://clang.llvm.org/docs/ClangFormat.html</a>" target="_blank" &gt;&lt;tt&gt;__clang-format__&lt;/tt&gt;&lt;/a&gt; is used for code forrmating.
- Installation (only needs to be installed once.)
- Mac (using home-brew): &lt;tt&gt;brew install clang-format&lt;/tt&gt;
- Mac (using macports): &lt;tt&gt;sudo port install clang-10 +analyzer&lt;/tt&gt;
- Windows (MSYS2 64-bit): &lt;tt&gt;pacman -S mingw-w64-x86_64-clang-tools-extra&lt;/tt&gt;
- Linux (Debian): &lt;tt&gt;sudo apt-get install clang-format-10 clang-tidy-10&lt;/tt&gt;
- Running (all platforms): &lt;tt&gt;clang-format -i -style="file" my_file.cpp&lt;/tt&gt;
@subsubsection autotoc_md32 GitHub Actions
- Enable GitHub Actions on your fork of the repository.
After enabling, it will execute &lt;tt&gt;clang-tidy&lt;/tt&gt; and &lt;tt&gt;clang-format&lt;/tt&gt; after every push (not a commit).
- Click on the tab "Actions", then click on the big green button to enable it.
&lt;img src="<a href="https://user-images.githubusercontent.com/51391473/94609466-6e925100-0264-11eb-9d6f-3706190eab2b.png">https://user-images.githubusercontent.com/51391473/94609466-6e925100-0264-11eb-9d6f-3706190eab2b.png</a>" alt="GitHub Actions"/&gt;</p>
<ul>
<li>The result can create another commit if the actions made any changes on your behalf.</li>
<li>Hence, it is better to wait and check the results of GitHub Actions after every push.</li>
<li>Run <code>git pull</code> in your local clone if these actions made many changes to avoid merge conflicts.</li>
</ul>
<p>Most importantly,</p>
<p >Most importantly,</p>
<ul>
<li>Happy coding! </li>
</ul>
@@ -320,7 +330,7 @@ GitHub Actions</h3>
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="../../doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="../../doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.2 </li>
</ul>
</div>
</body>