Any given software project does well to follow certain common rules. It's not so much that any given rule is better than another, but rather consistency is valuable so that, if everyone knows and follows the rules, decision paralysis is avoided, the project is more organized and easier to work on as a group.
There's still plenty of code in CodeCombat that doesn't follow these conventions. If you find any, please fix it.
- For the sake of brevity, names that need to incorporate "CodeCombat" can be abbreviated to "Coco" (for CS) or "coco" (for Sass).
- Names that have acronyms such as "id" or "html" should be capitalized the same as word for CamelCase names. So
idan acronym? ... Sure!)
- Lines should generally be no more than 119 characters, but for long comments or lengthy data, it's fine to exceed this amount. We recommend enabling soft-wraps on your editor.
- We don't use spaces around default parameter values:
containsPoint: (p, withRotation=true)instead of
containsPoint: (p, withRotation = true). (We did a lot of Python in our youth.)
- We carelessly mix single and double quotes. Guess we could fix this.
- We prefer standalone
Note that Brunch automatically fails to compile when certain rules aren't followed, using a selection of CoffeeLint rules. Keep an eye out for rule failures in Brunch output for guidance here.
The commands listed below can be slow and it's recommended to install an editor plugin for faster feedback.
npm run fix will run
standard --fix on the entire codebase ignoring certain directories.
npm run fix <filename> will run
standard --fix on a single file.
npm run standard will provide linting info for the entire project.
npm run standard <filename> will provide standard linting info for a single file.
Commenting and JSDoc
Try to avoid writing low-value comments. Comments should be mainly used to flag areas in need of improvement or that really need some explaining. Ideally, code should be structured so that reading the raw logic reveals what it is doing and how it is doing it. If a function is long and convoluted, break it down into many clearly named functions. If it's not clear what a function does, rename or otherwise refactor it to make things clearer.
It is recommended that comments follow JSDoc conventions. Often your IDE will help you but their website is an excellent reference.
Many JS editors such as VSCode automatically include JSDoc comments on hover, and will then also provide methods or properties appropriate for the type referenced in the comment.
Breaking CodeCombat Down Into Third-Party Modules
Aether and Treema are built from the ground up to be modular and not tied to CodeCombat, because they're large projects that we could imagine being used in a variety of other projects. There are other parts of CodeCombat which could be spun off into separate, fully autonomous projects. These projects do need to be fully autonomous, though, in terms of code. Treema and Aether are built not to have anything specific to CodeCombat. If more parts are to be spun off, they need to be generalized enough to be useful to others and without irrelevant cruft.
Leveraging Third-Party Tools
CodeCombat uses a great many open source libraries for both client and server, and are summarized in the wiki. Familiarize yourself with these tools and use them whenever possible. Try to avoid re-inventing any of the many wheels included in the codebase. In particular, read through the documentation on Backbone, Bootstrap, Lodash, and jQuery.