Code Thesaurus Best Practices
Code Thesaurus is a reference tool for what exists in a language to compare simliar concepts in other languages.
These are the best practices for how to write an entry to Code Thesaurus. In code there are multiple ways to solve the same problem. It will be easier to compare each language's implementation of a concept if the main difference in the
Concept Card is in the syntax and not in the descriptions.
These are the guidelines to fill out a concept card.
- Code blocks must technically compile. It should work in production.
- Leave comments out of code blocks and put in comment blocks instead.
- Try to have code blocks match other code blocks as much as possible. The code blocks should match chronologically and structurally.
- If there's more than one way to do things, you can write both in a code block, but differentiate them with a comment.
- Anything that's not intuitive to a beginner needs a comment. Don't assume everyone knows the "easy stuff". This is a learning tool and new learners might be using it. They may not know what is automatic to an experienced developer.
- Operators need to show order (prefix, postfix, infix)
- You should have
code + comment, or
not-implemented + comment
- When the Implementation (code block) is text and not actual code, use
hash marksto identify key words or syntax.
- If a concept doesn't appear in a language, do not add it(Don't write an algorithm to do equivalent functionality).