Code Thesaurus Architecture
The project is broken down into several parts. The idea is to make it as easy to edit by abstracting out as much of the site from the language information as possible, then also to separate out all of the language information so they're as easy to work with as possible without needing to know additional languages.
The main way this is broken down will be: * Website (codethesaur.us) * Programming language data files * (later) meta data for other types of comparable data
(info about site goes here)
The following may seem complex, but there are multiple issues that come to light quite quickly:
- Some languages are easy to compare (like C++, Java, C#) and others that aren't (like Haskell, Perl, APL, Whitespace, LOLCODE)
- Some languages should be compared against their versions, especially for those wanting to upgrade their code (ex: Python 2 vs Python 3, PHP 5 vs 7)
- Some languages have separate variations of the same thing (ex: ANSI C vs Microsoft C, .Net vs .Net Core languages, C64 BASIC vs QBASIC vs Visual Basic)
- Incomplete language should still be searchable. (If something isn't implemented in a JSON file, the concept may not exist but also just might not have been added yet. This should be distinguished somehow.)
- Data files should be easy to contribute to but powerful enough to fully describe language concepts/structures
- The project should be as easy to contribute to if you have one month of programming experience or 20 years or programming experience.
- Someone who wants to contribute to one language shouldn't be put off by having to filter through other languages.
- Some languages are compiled, some are interpreted. Some are designed for desktop/mobile apps and some are designed to run within browsers, are embedded, or have other constraints. These should be accounted for when comparing languages.
- Some concepts exist under different names (ex: Functions, subroutines, and methods are all the same thing)
- Languages have constructs that aren't built the same and should be clarified. (Ex: Arrays/lists can always be ints and start at 0, but some start at 1, or might be strings/hashes, or could literally be any other data type)
- It should be simple and easy to add a new language or version.
- The end user should have an easy to use site that's accessible.
- Opt for accessibility and ease of use over fancy frameworks.
Programming Language Data
Every programming language will be broken down into several parts, with data stored in JSON files: * Languages available (JSON file listing other languages) * Language name (directory) * Version number (directory ex: Java might be "8, 9, 10" while C++ could be "C++11, C++14, C++17" while Python could be "2.6, 2.7, 3.5") * Category type (JSON file; things like data types, functions, strings, file I/O, memory operations, DOM navigation, and more) * Meta info (language name, version number, release date, language types/categories, etc.) * Sub categories (ex: void functions, functions with limited parameters, functions with variable parameters, anonymous functions, etc.) * ID (something to standardize matching things up) * name (the concept/structure) * code (example of how it's written in code) * comment (explanation of parts of the code) * doesn't exist flag (for something that doesn't exist in a language
I haven't determined yet if it makes more sense to have a repo for language data vs individual repos for individual languages. Either way, something like a CI tool and/or Git Submodules can combine them together.
I wanted a combination of easy to read for a human, easy to parse for a computer, and not a pain in the butt to deal with formatting of strings, code blobs, and more things. YAML would be great except for the formatting, XML is just verbose, and some form of custom file would require training. There's other serializable formats too, but JSON seemed easiest.
What Should Be Included?
It's still the early stages, and things can change. I'll also probably forget things somewhere in here. Reach out if you're interested in helping make further improvements or if there's some piece I've forgotten.