Skip to content

Communication & Design Rules

Jump to bottom
alloy edited this page Sep 23, 2014 · 15 revisions

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 ‘sut’, ‘foo’, ‘bar’, or even ‘baz’. Unless you are referring to somebody named ‘baz’, the context is people, and most people know who ‘baz’ is, symbols like these are not self-explanatory.

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

  • Assume that somebody is not a native English speaker. Keep this in mind when somebody is not understanding your “clearly defined” sentences and re-phrase accordingly. Also, things like ‘fuck’, ‘deserves a kneecapping’, etc, might be totally friendly where you’re from, but the person you’re communicating with is probably not where you’re from and you might scare them.

  • 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.

  • Avoid sarcasm. Sarcasm translates hard without face-to-face body language and is usually taken in a bad way when misinterpreted. This is often accompanied with the use of emoji to covey that no mean-intentention was intended, but, as stated above, emoji meant for this reason should be avoided.

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”.

  • User convenience trumps design principles such as avoiding code duplication (DRY) Unless it introduces much much much more complexity than the convenience it provides, the user-experience should always be taken into account first. Avoiding code duplication is not a good enough reason in and of itself to divert the burden to the user of the program.

  • 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.

Clone this wiki locally