Communication & Design Rules

Communication Rules

• Listen for arguments in discussions, ignore feels. Ok, we need to get this one out of the way as soon as possible: Discussions need to be direct and without bullshit. Critique is the highest good in our OSS economy, so embrace it and try to stay away from defensive comments. We already have plenty of messages to read, so keeping it to functional (and as succinct as possible!) messages will ensure we don’t subconsciously start ignoring you for the amount of noise. It’s harsh, but c’est la vie.

• Be explicit, don’t use anaphoric references.

• Be verbose where it increases clarity, don’t use acronyms.

• Use real-world static examples, don’t use variables like ‘foo’, or ‘bar’, or even ‘baz’.

• Keep asking “why?”. Really understand the reasoning behind a requirement before implementing.

• Avoid the use of emoji to convey if a message is well-intentioned. Instead, don’t ever write mean-intended messages. People might read mean-intention into your message, but once you start adding emojis to clarify that this is not the case, then you might have a hard time if you forget to add an emoji the next time. Instead, let’s assume we all have the same intent of improving the project.

Design Rules

• KEEP IT SIMPLE, STUPID Do not try to tackle possible future issues until they come along. Do not tackle existing current issues when the issue is a corner case affecting only a few people and the code required to fix it is more than a few simple lines. I.e. the benefit of the change has to outweigh the complexity required, that it adds to the code-base, to fix it.

• Options are the work of the devil. This is always true. You should try to strive for less options, never more. When there’s the feeling that some functionality does not fit in the scope of any other existing option, then maybe those existing options need to be revisited first.

• Keep it lean. Pretty closely related to the above ones, but possibly less obvious to people. Keeping things simple also means not pulling in new dependencies without thinking hard about how to otherwise solve the problem. When in doubt, remember “you do not need another queueing system”.

• Know required details first, then think of how to design and implement. This means that you should not assume to know how a Xcode/compiler/linker issue works, but first manually verify how something works and be open sure to test out different approaches. A solution based on assumptions only is not acceptable, ever. Once you have the data, only then decide the best course to take, always keeping the KISS principle in mind and thus choosing the simplest course.

• Implementation over discussion. Do not keep discussing to reach an implementation. Discussions often contain assumptions and just as often these will be wrong. At some point a bare bones implementation will make further discussion much easier. When doing this, do not feel like you need to have something polished to show to the team, because it should be possible to throw away the code without feeling bad about it.

• Once you are a proven ‘pro’ at X, you may selectively ignore rules. Many of the things described in the list do not always apply in all cases. The key here is that as a ‘pro’ you should know when it’s ok to make an exception and you should be ready to defend your decision with fact based arguments, otherwise you will fail to get it passed our scrutiny. Once you’re a ‘pro’ at X, it’s perfectly ok to use hyperbole to make things clear for the general case (i.e. on tickets as well). Some people need to be told in direct terms before accepting that path X has been tried already.