Principles for Developing with Pavilion

I’m not normally ‘preachy’ about principles, but I think it’s good to lay out how I think about software development once so you know where I’m coming from. If you have any thoughts on these, or your own you’d like to add, reply on this topic.

  • Value to you. You should only keep doing this as long as you feel you’re getting something out of it, and you feel it’s doable within the context of all your other responsibilities. If it becomes a chore, or you need to stop for some other reason, just tell me l and I will understand with no hard feelings.

  • Learning what’s necessary. We’re going to be learning by focusing on specific goals (features or fixes). Understanding of Rails, Ember and Discourse itself will come as a side benefit of accomplishing those goals. (See further: Learning Ember.js before developing on Discourse and ‘how to build stuff if you’re a newbie’ ).

  • Ignore the complexity. Try not to focus on the fact that you’re working in a complex environment (i.e. the Discourse codebase). The feeling “this is too complex and hard” can be a really powerful one, particularly if you’re stressed, tired or are stuck on something. If you feel this coming over you, take a break. Ignoring the complexity also means that you don’t have to understand how everything works in order to achieve your goal. I know it feels like you should understand it to do it ‘properly’. But you need to keep this feeling in check somewhat otherwise it can stress you out and get you down. This doesn’t mean you should be sloppy or careless. It means you need to be aware of when you’re getting too sucked down a rabbit hole. Don’t give in to your perfectionist or completist impulses.

  • Persistence over Brilliance. A key psychological trait you need to be a decent software developer is persistence. When you’re managing a team of developers you cherish those who are persistent and don’t give up. Sometimes, the most brilliant developers are quite unproductive. This doesn’t mean you shouldn’t aspire to excellence and do inventive things. It means that, no matter how smart you are, decent software can only be built over time through persistent effort, iteration and by listening to your users. This is the primary reason I now have a bunch of plugins that a wide variety of people use. It’s not because I’m an amazing developer, it’s because I’m persistent.

  • There are no sacred cows. There are many problems with my code. There are even some problems with parts of the Discourse codebase. I am often wrong. Sometimes the Discourse team is wrong. Often when people request a feature, or point out an issue, they are misunderstanding something or are asking for something untenable or inadvisable. The fact that you’re here means that you’re a critical thinker. If you think something is incorrect, needs adjusting or at least needs questioning, please say so.

  • Work by example. This is the flip side of “There are no sacred cows”. The starting point when trying to solve any problem should be “Where is this, or something like this, currently implemented?”. Think about that purely from the point of view of a user. For the majority of things you’ll do there will be an identical or very close analog in Discourse or an existing plugin. Start by copying that.

  • Don’t reinvent the wheel. This is important. Discourse is packed with hooks, helpers, libraries and ways to integrate custom code. The core of this is the plugin api on the client and the plugin methods on the server (see lib/plugin/instance.rb ), but it goes some ways beyond this. You will come to really appreciate how much effort has gone into making Discourse as extensible and customisable as possible. If you initially implement a piece of functionality that replicates, or doesn’t take account of, an existing piece of functionality in Discourse I will ask you, and help you, to use the existing Discourse hook, helper or integration.

  • Ask questions. Never suffer in silence. I love questions. If you don’t understand something, or have really hit a wall, just ask. It’s the main reason we’re doing this.