mirror of
https://github.com/GTNewHorizons/Mantle.git
synced 2026-11-18 11:19:20 +00:00
2.9 KiB
2.9 KiB
Contributing to Mantle
We love to see new ideas realised by people, however as a shared library we need to demand pretty high standards for all contributions. Failure to adhere to these can result in your PRs being rejected!
Coding Style
- We use Scala for all classes within Mantle. This is a single-language environment. Java code will be rejected.
- Scaladocs (much like Javadocs in form) must be provided for all methods, with the following:
- One-line summary of method purpose/function
- Optionally, a detailed paragraph about the function; limitations, known issues, how to use safely etc should be in @note tags.
- @example tag if needed to clarify use
- @param tag per parameter
- @returns tag for non-void methods
- Scaladocs must also be provided for classes.
- One-line description of class e.g.
Mantle-Core object repository - More detailed description of what the class is for
- @constructor and @param as appropriate
- @author tag in the form
@author GitHubUsername <[email protected]>(Note that the email section can be dropped if you feel the need) - Additional authors can be credited in additional @author tags.
- Don't add yourself to @author if you just made a small change; the tag is intended for the original writers.
- One-line description of class e.g.
- Scaladocs sit above any annotations on the class/method
- Do not provide Scaladocs for variables! Just name them something logical and not too long.
- Use 2-space tabs (this is recommended form for all Scala projects)
- Use immutable
valentries instead ofvarwhere possible - Only
valobjects should be public exposed;varobjects must be private and hidden behind getters/setters. - Ideally, all access should be as restrictive as possible;
varvalues must always be private- Getters/setters follow normal method rules
valvalue should be private if only used internally, protected if only within the package and public if it's world-readable (or needed outside the package)- Methods should have the minimum access required to be useful (private for internal, protected for intra-package/subclasses, public for world)
- Variable names are in lower camelCase - An upper character for the start of every word except the first.
- Use of Functional Programming idioms is recommended, but not necessary (not everyone has been trained in this, and we acknowledge that)
- In particular, I (Sunstrike) would highly recommend atleast getting to grasps with the functions
map,filterandfoldin general (Scala or otherwise) - Also remember that functions are data in FP. We can pass functions around just like values. This may be used in idiomatic code.
- In particular, I (Sunstrike) would highly recommend atleast getting to grasps with the functions
Perhaps most importantly out of all this, please apply common sense -- If you think your code looks a mess, it probably is! Tidy up and when you're happy with it, send us a PR and we'll give feedback if it's in a state we won't pull.