Hey all,
I started to put down a list of the stuff I learned over the past
few weeks from my involvement with Phobos. What do you think
about reworking the contribution guide with small helpful hints
and checks?
https://github.com/D-Programming-Language/phobos/blob/master/CONTRIBUTING.md
This list is not complete by any means - however you might also
have small bits that you learned or words of advice that you
would like to give to newcomers?
Code
----
- dont add @nogc, @pure, @safe attributes yourself - let the
compiler infer it!
-> add unittest check for @nogc or @safe if possible
- use nested structs for ranges
- avoid to use `auto` as return type
- some parts of Phobos are a bit older (there are some relicts
when the compiler was lacking functionality) - don't be afraid to
use the new features (e.g. Foo!Range vs. Foo!(Range))
- check: did you stick to the style guide? (e.g. braces in their
own lines (allman style) or white spaces between operators)
- check: is there an easier/more performant way to do it?
- check: is your code flexible enough to accommodate more use
cases?
- check: did you add enough tests?
- check: read through your code again - is there any part that is
not understandable?
Naming
------
- ping @andralex for approval of new methods/functionality
Documentation
-------------
- use backticks `code` instead of $(D foo)
- start with a capital letter in all blocks of the method header
- use $(REF) for links to other methods (format is $(REF
_stripLeft, std, algorithm, mutation)) - $(REF_ALTTEXT) for a
different link name
- variables will be automatically put in backticks, use an
underscore to avoid this behavior (e.g. _foo)
- don't put examples in your ddoc header - use the `///` magic to
annotate them.
- check: did you add Params, Returns, See_Also sections?
- check: read your documentation text aloud - is it
understandable?
- check the output of CyberShadows's DAutoTest of the
documentation
As a last word, a couple of this things could be enforced -
especially the style guide. Are there already plans to check for
this automatically?
