… catching yourself writing about coding at 1am.

• Anyone on the forum have any experience with the creation of "This is how we write software here" guidelines?
• Anyone on the forum have any experience with reading "This is how we write software here" guidelines? What worked well and what didn't?

I'm at the stage of considering employing more developers (let's forget the HR/business side of employing people, I've got that side handled just fine). I used to have some guys working for me, although I didn't replace them as they left for various reasons. I recall from back then, that I had a problem familiarising them with 'the house style' - in terms of overarching software architecture/design. This lead to boring-as-sin (for them) pair programming, and I don't think even that was a very efficient way of teaching them the house style.

I'm trying to come up with something that won't be an immediate information-overload for the newbies. Equally, I want to get them acquianted with "the way I want them doing things" as quickly as possible to minimise lost productivity. IE: I spend as little time as possible shaking my head and telling them they're Doing It Wrong™. I suppose I want to try and condense some important design patterns that I swear by into a "dos and don'ts" guide.

Right now I'm writing it out as a Freemind mindmap, it's getting pretty big though. Any other suggestions or insight from experience?

I'm toying with the idea of stripping the actual reading guide down and writing a small(ish) sample application with a simple-enough domain. Then I can point them to that as an example of "Here's something done right". Probably something like a calendar/scheduler application, that's fairly simple but should make use of all of the appropriate design patterns I'm trying to familiarse people with.

Another idea that just occurred to me (no idea why it took this long) is to leverage some of the design pattern books on my bookshelf. I just realised that I have some great hardcopy books in the office and "for further reading and explanation" I can direct the employee to a page number in one of those. No need to re-write what Eric Meyer and Martin Fowler already wrote.

I suppose my main problem is that I am having a hard time getting into the mindset of my intended audience and coming up with something that will be useful to them. Thought I might see if there's any experience here that I can tap

Now sleep!

This worked beautifully for me: http://pegasus.pimpninjas.org/black/commandments
Is this what you're looking for?

I have no idea what your house style is, and if it's even compatible. But a few tenants that they should follow could be all they need?

Hire sociable geeks only!

As geeks, they should be able to cope with any technical challenge you throw them. Assuming it's in their field.

As sociable, they should have enough empathy to understand that there's a reason for a house style i.e. other people will have to deal with their work. No write-only source files.

Wherever I've worked, I found the best way of getting style conformity is just to explain to them and allow them to take their own notes. Yes, a reference document would be useful as a reminder, but it's not essential unless you've a huge list of demands and constraints. In which case they may just want to run away... Maybe you could prepare a presentation which covers the main areas and provide more detailed notes for a reference. The more care you put into doing that means less time spent head-shaking and rewriting code.

Anyway, IMO it's the nature of the potential employees and their ability to fit in which is the most important part.

Good info.

@Katorone - I'm really talking about much deeper things than that commandments page talks about. I'm really thinking about things such as how I use the Service Layer pattern as part of the architecture of the app. This includes what the responsibilities of the service layer are (IE: what logic to put in there and what not to put in there), as well as how it should react to problems 'downstream' in the domain model layer. Service Layer is just one of many wide-reaching design patterns I use and (as everyone does), I have my own twist on it - I want to try and efficiently communicate that twist.

… the best way of getting style conformity is just to explain to them and allow them to take their own notes.

That's true; a lot can be said for good induction and induction material. I feel like I have a bit too much to say though to do it all in that format. I've been thinking it through over the past day (whilst boggling at some ridiculous code that needs urgent refactoring). What I have in mind to develop right now is something like:

Some 'induction materials' (a LibreOffice Impress presentation could be useful for this) that punctuates a ~30 min induction 'lesson'. Really it introduces the employee to the overall structure. That's how the app layers stack up (which layers I use and their overview roles). Also, the names and high-level overview roles of the technologies and programming frameworks that I regularly use, of which there are about six). Finally, I need to make sure they're aware of git & MantisBT (so they can actually participate in a project).

Then, at the end of the induction I'd like to give them access to some (electronic) reference material (perhaps in mindmap format) that has the more detailled guidelines for how to develop within each layer of the application. For example: "If you're writing domain model APIs, this is how you structure them".

Within that reference I can leave the detailled explanations of the "why" out. My natural instinct is to explain the "why", because I for one remember things far better when I understand the reasons for them. The "why", though, has already been written for me, I can provide footnotes along the lines of "For a detailled discussion for the rationale behind this, see Patterns of Enterprise Application Architecture [Martin Fowler], page 133" (the book is actually on the bookshelf in my office).

That establishes a conceptual separation between the "rules that must be obeyed and read thoroughly" and a lot of high-level technical discussion about why those rules lead to writing good software. It might help prevent some of the perceived information overload that the employee would be subjected to if I placed the rationale right next to the rules themselves. IE: If the explanation for the rules were printed right next to the rules themselves then the reader is likely to think that the explanation is also immediate required reading. If there's instead a footnote that says "if you want to know more, go read this" then the psychological effect is different and I should be able to keep their focus far more narrow.

The other thing is of course - different people learn in different ways. I am (extremely) lucky to have a highly visual/conceptual mind along with a very good visual memory. If I see a diagram of something I will remember it almost forever. Conversely - tell me something verbally and I'll forget it really easily. But - the way I learn things is not the only way.

(yes, I used to work in education and still have friends/family who make a living from teaching).

Anyway - I'm still out for ideas, nothing's set in stone yet!

Ah, I also thought you were referring to coding practices and style, e.g. indentation and brace placement On occasion I've worked with people who just wouldn't use any consistent indentation, and even code inspection was a nightmare, let alone having to work on it.

OK, you're covering several distinct but related areas; the architecture, the development methodology and the tools.

You'll need to tell them why that particular architecture is used, even if they don't need to interact with most of it. Include mention of any standards you're conforming to - "We're using the Beretta layer so as to conform to ISO-007". Don't leave them thinking "why on earth did they do it this way?" for any of it. Give them enough context so they understand how their end fits the larger picture.

The dev methodolgy description will slot into the architecture explanation, but mostly you need to explain that in terms of functional specs of the apps you want developed. Again, make sure they understand the context and why the methodology applies to what they'll be doing.

Tools can be tricky; most devs want to get on with coding and building, and don't want to be bogged down by the minutiae of delving through tool documentation. If the tools are relatively common and intuitive then there should be no problem, but make sure they're aware of anything out of the ordinary e.g. required precomiler directives or any structural conformity needed for unit testing. Watch out for the catch-22s - don't pass up the chance to gain a good developer just because they haven't used certain specific tools, as long as they're familiar with the ideas behind them e.g. debuggers. Good devs can clamber up any relevant learning curve you throw at them, and everyone who's good with a particular tool had to start learning it sometime.

OK, that's my punt!

On occasion I've worked with people who just wouldn't use any consistent indentation, and even code inspection was a nightmare, let alone having to work on it.

This is not a problem for me, in that it's trivial to fix. Whilst I would like devs to use the same indentation style as me, worst case scenario I load their source into MonoDevelop and hit "Edit » Format Document". Zing! It's reformatted just the way I like it!

most devs … don't want to be bogged down by the minutiae of delving through tool documentation

Yeah, for the most part Mantis is just a bugtracker and it's fairly self-explanatory. Only things I need to teach is the definition of bug severity levels and the differences between them: Block/Crash/Major/Minor/Tweak/Text/Trivial/Feature. Also the difference between bug severity (user impact on the utilisation of the affected feature) versus priority (client-specified/business-case urgency of fix).

The one that (in my experience) the guys get totally bogged down with is the git version control system. Especially if they're not Linux natives and are scared of the commandline. Oh that is so much fun. My strategy so far has been to get them using only "git add -a", "git status", "git commit", "git pull" and "git push" on day 1. If they need to do anything else (they will) I sit with them and talk them through it as they need to do it on a case-by-case. Eventually they'll be doing their own merges and the like.

Git is an amazing system (it would be, it was initially written by Linus Torvalds) but to really use it to its full potential you need a deep understanding of the underlying principles of how it works and that's something that can take a year or two to fully learn (assuming you're just using it as a standard developer/user and not studying it specifically).

ToreadorVampire wrote:This is not a problem for me, in that it's trivial to fix. Whilst I would like devs to use the same indentation style as me, worst case scenario I load their source into MonoDevelop and hit "Edit » Format Document". Zing! It's reformatted just the way I like it!

True, and my bad memories are mostly from the olden days when people only used vi and emacs. However, the idea that devs need to work within a context and their work must be maintainable by others remains important.

The one that (in my experience) the guys get totally bogged down with is the git version control system. Especially if they're not Linux natives and are scared of the commandline. Oh that is so much fun.

Windows has a lot to answer for! I'm guilty too - I went from Unix & AmigaDos to Windows because of commercial pressure, though the appearance and skyrocketing of Linux has balanced that trend. Yeah, if there are major tools that need extensive experience, then you can't short-cut that. Most devs are familiar with source/version control systems, e.g. Subversion is pretty common, but it looks like Git is an arcane world peopled by obscure but powerful mystics...

I used to use SVN until (checks his oldest git repo) … October 2009, at which point I made the jump to git.

I will never ever consider going back.

OK, you've triggered my curiosity! I'm going to look into Git.