Notes for Contributors - acuminous/yadda GitHub Wiki

I'm delighted to accept pull requests, but would also like to keep the Yadda code base consistent with the following principles and conventions. Feel free to ignore them (especially if you're fixing a bug), but don't be offended if your code gets re-written before it's merged.

Mission

An application should do one thing well. Yadda's "one thing" is to map lines of text to function calls. It's not a test runner, or a test framework, but should be able to integrate with other tools easily. It shouldn't have a ridged "Given, When, Then" syntax either.

Feature Improvements

Before working on an improvement, consider creating an issue for it. It may be something I (or another contributor) has already given thought to and can help with.

Zero Dependencies

I don't want to force Yadda's user base to install underscore/lo-dash or async, so even though I like these libraries and would love to use them in the Yadda code base I've resisted.

Very Small Functions

The average size of a function in the Yadda codebase is around 2.5 lines, I'd like to keep it this way.

Else considered harmful

I don't mind guard conditions (an if statement near the top of a function that returns immediately or throws an exception), but try very hard to avoid else or switch statements. They are typically hiding a fork in behaviour that is probably better handled with polymorphism. Yadda only has one else statement in the whole codebase.

Booleans make bad parameters

Passing booleans as parameters leads to else statements. Else statements are bad. Use polymorphism instead.

Avoid Inheritance

I prefer composition, mixins or duck typing to classic Java style inheritance hierarchies.

Encapsulate, encapsulate, encapsulate

Did you know that the NASA Mars Climate Orbiter disintegrated because they didn't encapsulate quantities? The system on the ground sent thrust instructions in pound-seconds, but the flight system on the orbiter expected them in newton-seconds. When your software leaks primitives bad things happen. Please keep your behaviour and data as private as possible.

No Comment

There are two valid uses for comments. The first is to explain why you are forced to do something dumb or confusing - maybe you're working around a bug in a 3rd party library or implementing a complicated algorithm. If you use comments to explain code that is confusing for some other reason, then instead of writing the comment, take the time to simplify the code. The second valid use of comments is a one or two liner explaining the "job" of a class. This forces you to think about the purpose and scope of the class before you write it. If you find yourself writing comments to visually separate blocks of code, this is telling you that you should split the block up into separate classes or functions.

Automated Tests

Yadda's code base is pretty well tested and will continue to be so.

Syntax

I wrote Yadda just after completing a Ruby course. Hence why the syntax_follows_ruby_coding_conventions more closely than it does JavaScripts. Probably a mistake, but I'd like to keep the code base looking consistent.

Commit Access

I'm happy to give commit access to anyone making frequent contributions that meet the above criteria. The last thing I want to be is a bottleneck.