Category Archives: Gripes

The title says it all.

Interaction in team projects

I had an interesting experience over the summer, working in a small but diverse team on a single project for several months. I was contracted to design and maintain the build system, and so ended up getting involved in all areas of the project. As a result, I came across many of the problems which my team mates were having. A lot of these problems were my fault, some were my team mates’ faults; but a lot of the problems were a result of bad communication.

While this all occurred in a (unfortunately) closed source project, I’ve seen similar things happen in open source. I thought I’d come up with a list of suggestions for people starting out in the open source world, to try and help them understand the best way to interact with other people on the same project, or with their mentors in GSoC (for example). None of this is targeted at anyone in particular (especially not the GSoC students I had the pleasure of interacting with this summer)!

Thinking about this has been useful to me; hopefully I won’t do any of these things in future (because I certainly have in the past). I just hope it’s useful to someone, somewhere.

  • Don’t spam chats with half-written messages. Take your time and formulate your thoughts properly in a full sentence. Spamming messages just means the other conversant has to sit there and wait for the rest of the sentence, rather than getting on with something else.
  • Don’t join a chat, say “hi” or “someone please help” or “ping” and then sit there without giving more information. This just introduces an extraneous round trip in communication, since someone has to then ask what the problem is before they can start to help. Conversely, if someone joins a chat and says “someone please help”, don’t lecture them about it. Be patient, and help them as much as you can.
  • After asking a question in a chat, wait patiently for the answer to the question. Although they’d love to help, developers are not constantly looking at their chat client. If you leave a fully-formed question in the chat and then wait, a developer should answer in their own time.
  • If you encounter an error or warning (e.g. from a compiler or program) and want help with it, always provide the full error message and some context. The person who’s helping you isn’t psychic.
  • Always give context and be careful of over-using pronouns. “It’s running awfully slow” is not specific enough. What is ‘it’? What were you doing with ‘it’ when things slowed down?
  • Look at man pages and --help output before asking people. Documentation for established software (e.g. SVN) is generally quite good. The person who’s helping you will probably just look at the man page anyway.
  • Read VCS commit logs. Ideally, people will explain and justify all of their work in their commit messages, and mention things which you should be aware of. Reading the logs may well save you debugging later.
  • Use the correct terminology as much as possible, and don’t use that terminology in other contexts where it could confuse matters. Communication is a lot faster if a common vocabulary is used.
  • Learn your version control system and learn it well. It’s a tool you’ll be using every day, and making mistakes with it can be costly for your (uncommitted) work and/or for other people’s productivity. Always check the changes you’re about to commit, especially if conflicts have occurred. People will not take kindly to their work being overwritten because you’ve made a mistake, especially if it happens regularly.
  • If you’re making use of someone else’s code/APIs and you have a problem or can’t get it working, double check (against the documentation which they have written) that you’re using the code correctly. In many cases, the problem might be the way you’re invoking/using that code, not the work itself (thought such problems do suggest a lack of user friendliness in the work which could be fixed).
  • Always check to see if the code at least compiles before committing it to VCS. Committing something which doesn’t compile due to a trivial error shows a complete lack of testing or care. Compile it using the build system which everyone else uses, too. Manually invoking the compiler doesn’t count.

Coursework finished!

I've finally finished my A2 computing coursework, and I'll be handing in the writeup tomorrow! The program itself was finished (as far as the coursework was concerned; I've since added to it) a month or so ago, but the writeup itself has dragged on until now. I'll try and remember to release the source for the program in the hope somebody will find it useful, but I can't do that until it's all been marked and moderated, for fear of our Microsoft-centric exam board picking me up on it.

Unfortunately, my school have got worse as regards IT in that time. Previously, we only had a print quota system, where each user was limited to printing a certain number of pages — any more and the IT staff would have to extend their quota. Now, we've been told that we're not allowed to use school printers for our coursework, and instead have to print it out at home, as the school's running out of money. I find this a little far-fetched.

Regardless, I've spent half an hour this evening waiting for our slow colour printer to chug out the pages, and I'll be handing them the bill^W^W^Wit in first thing tomorrow, before browsing Wikipedia before lessons. Oh, wait, they've blocked it.

Grammar and punctuation

I'm fed up. I'm fed up of seeing poor grammar and lacklustre punctuation all over both the Internet and the world at large. It's not only embarrassing to the authors, but also spreads misunderstanding and confusion in some cases.

During a (rather long) journey I recently made, I saw the text "Melamine Faced MDF and Plywood" on the back of a van. Let's analyse the mistakes here (admittedly in a rather exaggerated fashion, but it's hopefully educational nonetheless).

First of all – and (in my opinion) the most prominent error – is the lack of a hyphen between "Melamine" and "Faced". To me, this makes it sound as if a person called Melamine faced (i.e. looked at) two people called MDF and Plywood. This can't be right! People may argue that we're all used to such mistakes, and that it is therefore acceptable. Other people may argue that we're used to frequent assaults by drunkards on innocent people. Get my point?

Secondly, neither "Faced" or "Plywood" are proper nouns, so why are their first letters capitalised? This is a sentence, and should be using sentence case: the first letter of the sentence and of any proper nouns should be capitalised, and the rest lower-case.

This brings me quite neatly onto my third and final point about this five-word disaster: it's a sentence, so it should end with a piece of sentence-delimiting punctuation, such as a full stop or exclamation mark.

After fixing all this, the sentence is much better: "Melamine-faced MDF and plywood.". Don't you think this is an improvement?

Moving into more general territory, I won't go into the age-old apostrophe rant, or the sub-rant about "its" and "it's"/"it is", but suffice to say, I'm not pleased about that either. :(

One thing I will go into is more HTML-specific — although it could be applied to all writing, and the terminology applies everywhere. It concerns hyphens and dashes; hyphens being the little horizontal lines joining words together (as in the example off the van), and dashes being the ones used to indicate sub-points (separate clauses) in sentences. My point is to do with the special HTML entities provided to cater for the two types of dash: the en-dash (the entity is –), and the em-dash (the entity is —).

Why do people insist on using hyphens to represent them? There are special entities/characters for them, so why not use them? Remember: hyphens join two words together, en-dashes are used in pairs (like brackets) to delimit a clause (an "off-topic" section/side-point), and em-dashes are used to indicate that the final clause or point of the sentence – the summation or answer, perhaps – is forthcoming. Em-dashes are commonly represented by some as two or three contiguous hyphens ("-​-"), which is also wrong, and hails for the command-line era.

My final point is again concerned with HTML entities — this time, the ellipsis. As an entity it is … and produces a nice single-character ellipsis ("…"), which is much better than the traditional use of three full stops ("..​."). Could people please get around to using grammar, punctuation, and HTML entities properly?