In order for your submissions have the highest likelihood of being accepted and to be maximally useful to users, we suggest following the guidelines that will be presented here.
Each sample provides a specific solution to a given problem. When submitting samples, we suggest making sure that the sample adds something when compared to the already submitted samples, e.g. different memory or cpu use characteristics, different algorithmic complexity or different design pattern usage.
When submitting samples, we suggest keeping in mind that Algoteka is a reference site, not a tutorial site. The target audience of the samples you submit will be mainly people who already have some familiarity in the field, so the code should focus on being readable and 'production ready' over being educational. Any theory and links to tutorials can be provided in the Further Reading section.
Important note: When you submit a sample, it will be unverified at first, which means that it won't be as easily accessible as verified samples. To find your unverified sample, follow the View all samples for this language link in any of the samples in that problem in your relevant language. If your language is new to the site (and thus unverified), you can find said language in the View all languages for this problem link on any of the language pages.
When a sample becomes verified its visibility will be greatly increased, but it might also get locked, meaning that any edits made to said samples will have to be verified by admins.
For each of the fields we suggest paying attention to the following:
An integer giving the ID of the problem the sample belongs under. Should be filled automatically when creating a new sample from under a problem. When logged in, you can see the ids of all problems on their own pages or on any sample under said problem.
The primary language of the sample. Ultimately the language this sample provides the top level abstraction for, the language in which it's functionality will ultimately be used. For instance, if you write a Python wrapper for C++ code, then the language will be Python. In case it's not clear which language it should be, you can submit the code to either, or all the primary language candidates, but we suggest creating your sample in such a way that there is only one top-level language.
All the libraries/technologies/packages your sample uses. In case a packages/library is not publicly available and named (e.g. they are a personal source-code repository), you should put in Custom Library. You don't have to explicitly tag the in-built standard libraries of the language, only anything that needs to be externally added/installed.
A concise title that will give an overview of your sample. Shouldn't contain information already given by the problem title, the language field or the tech tags field. In case there is no extra information to give here, we suggest a generic title like Sample. We suggest on empathizing the most important aspects of your submitted sample here.
A detailed description of the relevant characteristics of your sample, for instance the algorithmic complexity, the resource usage, the design patterns or just what the sample is going for. Can be left blank in case there is no information to add that's not already provided by the previous fields. It's a markdown field, and you can see its raw value for existing samples under the Sample Source link in the edit panel.
Here you specify what needs to be set up or what code needs to exist for this sample to be able to run. Can be left blank if your sample requires nothing beyond an ability to compile in its programming language and for the libraries/modules specified in TechTags to be set up. This is also a markdown field that can be viewed under Sample Source.
The most important field, providing the actual code of the sample. The code blocks you provide should have the language specified. In case the code is divided over multiple files, you should give the name of each file above the related blocks. This is a markdown field, and you can see the source for existing samples under Sample Source.
Example:
```c++
#include<iostream>
int main() {
std::cout << "Hello World!";
return 0;
}
```This is where you should provide the concepts/theory behind your sample and links to any additional resources that you judge as relevant and useful. The links should be provided with the format [webpage title] - [website name]. Can optionally be left blank. This is also a markdown field.
This is where you provide references to all the functions, classes, objects and anything else relevant from either the standard libraries or the external libraries. The provided reference(s) should:
std::min rather than min and django.urls.reverse rather than reverseThe references are provided in JSON format and can be edited in the JSON editor in either the Tree or the Code view. In the Tree view, we suggest appending the relevant "References Type" entries to the top level array, and filling them out with needed "Reference Entry" objects. In the Code view, we suggest making sure the JSON is comfortably formatted, which can be achieved with the top left format button or with Ctrl+I
When rendered, the entries will be automatically sorted by name. The raw source code for this field is available under the Sample Source link for existing samples.
Example:
{
"classes":
[
{
"name" : "std::deque",
"urls" : ["https://en.cppreference.com/w/cpp/container/deque", "https://cplusplus.com/reference/deque/deque/"]
},
{
"name" : "std::vector",
"urls" : ["https://en.cppreference.com/w/cpp/container/vector", "https://cplusplus.com/reference/vector/vector/"]
}
],
"functions":
[
{
"name" : "std::vector::push_back",
"urls" : ["https://en.cppreference.com/w/cpp/container/vector/push_back", "https://cplusplus.com/reference/vector/vector/push_back/"]
},
{
"name" : "std::deque::push_back",
"urls" : ["https://en.cppreference.com/w/cpp/container/deque/push_back", "https://cplusplus.com/reference/deque/deque/push_back/"]
},
{
"name" : "std::max",
"urls" : ["https://en.cppreference.com/w/cpp/algorithm/max", "https://cplusplus.com/reference/algorithm/max/"]
}
]
}In case you are the author of the code sample (didn't copy it from somewhere else) and in case you are fine with your sample being covered by the Algoteka MIT license, you should leave this field blank.
If the code you submit is already covered by an existing license that allows you to submit said code here, you should provide the copyright information here in the form of <year> <name of copyright holder>, for instance 2022 Algoteka OÜ
In case your sample is not covered by any existing license, just leave it as MIT License. In case your sample is covered by an existing license, you should specify which of the allowed license types it's covered under.
For markdown reference, we suggest checking the following cheat sheet: Markdown Cheat Sheet - markdownguide.org
The markdown used on this site had some differences from default use, for instance:
1. Line breaks are rendered
2. The code is properly highlighted when providing language in the code block, e.g. ```c++
3. LaTeX can be rendered with $ and $$
4. To resize the images you submit, you can use the HTML img tag, for instance: <img src="https://algoteka.com/media/user_files/2/python_bokeh_line_graph.png" alt="Bokeh Line Graph" width="450">
For examples on how the fields could be filled, we suggest checking the following sample source codes:
Creating a new page: Function view - algoteka.com
Heap: Using the STL priority_queue - algoteka.com
You can also create new categories and problems for Algoteka to which you and others can submit samples. We suggest creating a new problem when you have a sample you want to submit that isn't already covered by any of the existing problems. We suggest placing your problem under the most specific existing category that covers said problem. You can also create new categories, but we only suggest doing that if it's likely to contain many problems down the line and if the parent category has more than 10 problems/subcategories under it.
In case you have any questions regarding the creation of problems/categories (e.g. how they should be named, or where they should be placed) feel free to open a thread in the forums.
Important note: When you submit a new category or problem it will be unverified at first. To see unverified problems/categories, toggle the visibility button in the top bar of the Algoteka interface from Hide unverified to either Verified first or All mixed. You can also see them when you go to the page of the category under which your problem/category resides.
As with samples, once a category/problem is verified, it will gain greater visibility, but it will be more difficult to edit. Any edit made will need to go through a verification procedure.
For each of the category/problem fields, we suggest paying attention to the following:
An integer corresponding to the ID this category/problem should be placed under. When logged in, you can see the ids of all categories on their pages.
An integer describing where this category/problem should be positioned under it's parent, 0 means it should be placed at the very top, 1 that it should be placed below one category/problem, 2 that it should be placed below two others and so forth. Categories/problems should ideally be ordered by specifity, so more general categories/problems on top and more specialized ones below.
A title for the problem/category that quickly informs what it's about. We suggest keeping the title of a Category within 65 characters, and the title of a Problem within around 30-40 characters.
Here you can choose whether you are creating a new problem or a new category. Problems contain samples, categories contain problems and other categories.
A markdown field where you more thoroughly describe what this problem/category is about, what the samples under it should strive for and possibly provide any relevant context or supplementary material.