Adding Solutions
Authors: Nathan Wang, Benjamin Qi, Qi Wang
Contributors: Maggie Liu, Sathvik Chundru
How you can add your own solutions to the guide.
Prerequisites
See Working With MDX for additional information.
Steps
Fork the GitHub repository.
If it doesn't already exist, create a new
mdx
file insolutions/
including frontmatter, e.g. the following inusaco-690.mdx
:--- id: usaco-690 source: USACO Silver 2017 January title: Cow Dance Show author: Óscar Garries --- [Official Analysis](http://www.usaco.org/current/data/sol_cowdance_silver_jan17.html) ## Explanation (add explanation here ...) Use `\texttt{}` around variable names with length *greater than one*, like so. Place long equations on separate lines with display math, and use `\cdot` instead of `*` to denote multiplication. $$ \texttt{arr}[i]=2\cdot (a+b+c+d+e)+\sum_{j=0}^{i-1}\texttt{arr}[j] $$ Some additional text styles which you might consider using: http://latexref.xyz/Font-styles.html http://applied-r.com/latex-font-styles/ $func(var)$ $\textit{func(var)}$ $\textrm{func(var)}$ $\text{func(var)}$ $\textsf{func(var)}$ $\textbf{func(var)}$ $\texttt{func(var)}$ ## Implementation **Time Complexity:** $\mathcal{O}(N\log^2N)$ ^ Format time complexity like this. Should appear outside of `<LanguageSection>` if it's the same for all implementations. If you need to link to a module, format your link like [this](/silver/binary-search) instead of [this](https://usaco.guide/silver/binary-search). <LanguageSection> <CPPSection> (add cpp code) </CPPSection> <PySection> (if you have Python code) </PySection> <JavaSection> (if you have Java code) </JavaSection> </LanguageSection>
Keep file names and solution IDs consistent. In particular, the ID for a USACO problem (such as the one above) is the number at the very end of the URL on usaco.org. The name of a solution file should match the ID of the solution it contains. See Working With MDX for more examples of IDs.
Add your implementation, following these conventions below. It is not necessary to add an alternative implementation in the same language as the official implementation unless the alternative implementation takes a different approach or is better than the official one.
In the module's
.problems.json
file (in this case,Binary_Search.problems.json
), change thekind
of thesolutionMetadata
field tointernal
and remove all other fields. Also add tags (if you want). If the problem is not in a module, you can add the problem toextraProblems.json
.{ "uniqueId": "usaco-690", "name": "Cow Dance Show", "url": "http://www.usaco.org/index.php?page=viewproblem2&cpid=690", "source": "Silver", "difficulty": "Easy", "isStarred": false, "tags": ["Binary Search", "Sorted Set"], "solutionMetadata": { "kind": "internal" } },
Check that both the module and the solution render properly using the live editor before submitting a pull request.
Code Conventions
Since code for the USACO Guide is contributed from several authors, code style will not be uniform. Of course, we still strive for code that is readable and understandable. If any code does not compile or is hard to read, contact us.
Read our guidelines below before contributing code.
General
Use tabs rather than spaces to indent.
Pro Tip
If your code is indented with spaces, paste your code into the Guide Editor, right-click, click "Command Palette" from the menu that pops up, and then search for "Convert Indentation to Tabs."
In general, do not include unused code (e.g. "templates").
- There are some exceptions to this guideline (e.g. when using the
Kattio
class for Java I/O). In this case, collapse it with aCodeSnip
.
Lines should not exceed 80 characters. If you need to, split comments across multiple lines to follow this rule.
Use universally understandable variable names, especially for Bronze and Silver. Should be more descriptive than what you would normally use in-contest.
Add comments throughout your code to explain your logic. Feel free to copy-paste the official USACO solution and improve it by adding more descriptive variable names and helpful comments. Though keep in mind the following guidelines from Google's C++ Style Guide:
But remember: while comments are very important, the best code is self-documenting. Giving sensible names to types and variables is much better than using obscure names that you must then explain through comments.
In general the actual name of the variable should be descriptive enough to give a good idea of what the variable is used for.
Self-describing code doesn't need a comment.
Be consistent about formatting your code, unlike the following snippet. We don't care about which one you use (
a+b
ora + b
), but pick one and stick with it throughout your entire code.a,b = (0,1)print(a+b)print(a + b)Don't repeat yourself.
Once you've finished making the changes requested by a review, make sure to re-request the review.
C++
C++
Do not use variable names that could conflict with
using namespace std
. For example, don't name astd::set
"set."Do not use variable-length arrays as discussed here; they are not part of the C++ standard.
Do not include code that doesn't do anything. In particular,
- Do not include
cout.tie(nullptr)
as discussed here. - Do not include optimization pragmas unless you show that they improve performance.
For Bronze through Gold in particular, do not use additional macros (especially loop macros) beyond the ones listed below (see Github #806):
Code Snippet: C++ Short Template (Click to expand)int main() {setIO();}
Optional reading:
Resources | ||||
---|---|---|---|---|
LLVM | How to automatically format C++ code with links to style guides | |||
CF | C++ style guide | |||
useful reference, but mostly not relevant to competitive programming |
The C/C++ extension for
Visual Studio Code
supports code formatting using clang-format
(details
here). To
indent using tabs, include the following in your
C_Cpp.clang_format_fallbackStyle
setting.
{ UseTab: AlignWithSpaces, TabWidth: 4, IndentWidth: 4 }
You don't have to use a formatter, but doing so will ensure consistency across the guide.
Java
Java
- Regarding I/O,
Scanner
is significantly slower thanBufferedReader
and should be avoided. You may use your own I/O template, but collapse it as described above. - It is good practice to not use constant size arrays in Java.
- Use polymorphism when possible.
- For example,
List<Integer> list = new ArrayList<>()
instead ofArrayList<Integer> list = new ArrayList<>()
.