Skip to content
January 29, 2013 / Damien Irving

Programming with style

While this post focuses on programming in Python, similar style guides and static code checkers exist in other languages.
In my experience (which is consistent with that of many others), the fastest way to improve your programming is to show your code to other people. The most obvious payoff is that somebody might identify a critical error in your code, however the benefits of code sharing go far beyond that. For starters, it forces you to put more thought into your programming. You can get away with writing ugly, inefficient and poorly documented code for years if you know that nobody is going to see or use it, but this will eventually catch up with you. Someday a journal editor, research collaborator, colleague or job interviewer will request to see your code, and you’ll wish you’d addressed your bad coding habits all those years ago (see this YouTube clip for a very funny example). Secondly, code sharing tends to be a two-way process. Reading other people’s code is a great way of learning new techniques and approaches, particularly in a team environment where the code is highly relevant to your own work and the spread of knowledge and good practices is so critical.

So if code sharing is so wonderful and straightforward, why isn’t everyone in the weather/climate sciences sharing their code all over the place? One of the biggest impediments would have to be self esteem (or a lack thereof). I can remember the first time that I checked code into a shared version control repository – I was terrified. I had visions of my code becoming the fodder of endless jokes at morning tea (or worse – behind my back). In my job interview a few months earlier I’d been talking up my skills, now I was going to be outed as a fraud who barely had a grip on the very basics of Python programming! Unsurprisingly, this is not what actually transpired. Not only did I receive useful tips from knowledgeable colleagues, but people actually started turning to me for programming advice.

Ok, so I’ve hopefully convinced you that code sharing is a worthwhile and non-threatening thing to do. In previous posts I’ve even described useful platforms for sharing code, such as version control hosting services and It would still be reassuring to know that your code was looking slick and professional prior to sharing, especially if you eventually get to the point where you are sharing beyond your own research group. That’s where coding standards come in. The Python community has formalised some recommended programming styles to help everyone write code in a common, agreed-upon style that makes the most sense for shared code. This style is captured in PEP-8. Pretty much every aspect of programming style is covered in this document, from code layout (e.g indentation, white space and maximum line length) to naming conventions (e.g. when to use CapWords or under_scores) to documentation (e.g. DocStrings and comments).

While PEP-8 is actually a relatively short and interesting read, it would be a nightmare if you had to manually check your code against it every time you wrote a new program. Luckily, there are a number of static code analysers out there that check whether your code has captured the essence of PEP-8. From all the reviews I’ve read, it appears that Pylint is the best available (e.g. review from Doug Hellmann). Related documentation and tutorials can be found at logilab.

Even if you don’t anticipate that you’ll be sharing code in the immediate future, I’d highly recommend integrating Pylint (or a similar code checker) into your programming right away. I’ve been using it for about a week now, and already the readability of my code has improved dramatically. Not only will this make me look like a better programmer (lets face it, we all want this) on my personal Bitbucket page and when I eventually come to post my code on, but it also means that when I come back to a code after a few weeks/months, I’ll be able to much more easily recall what the code actually does!


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: