A Matter of Style

In this lesson we’ll cover a number of things that don’t fit anywhere else but which are essential to getting you on your way as a beginner programmer.

Style

As with any other type of creative writing – make no mistake, writing code is a creative activity! – different people have different styles. Extending the language metaphor, different programming languages have different styles as well and you can often tell what programming language someone learned first (or best) by the way they write their code in any programming language. While it’s nice to work in the style that is considered ‘best’ in each language, what is more important is that you are consistent in how you write: that way, another person reading your code can get used to the way that you write and make better sense of what you’re trying to say.

Variable Names

So here are some common styles for variable names:

Variable Name	Language	Rationale
my_variable	Python, Perl	Underscores (“_”) make it easy to read ‘words’ in a variable name
MyVariable	Java	Mixed Caps makes for shorter variable names that are easier to type
my.variable	R	R allows full-stops in variable names, no other language does

Comments

Commenting code that they’ve written is something that programmers normally hate doing, because it’s not doing work after all… until you have to try to understand what you’ve done and why two days or two months later. You’d be surprised how quickly your memory of why you did something one way, and not another, will fade and, with it, the risks that you were trying to avoid.

True Story

At least one (maybe more?) of your teachers briefly took out the company web site on at least two occassions because of poor commenting practice: there was some sloppy-looking code whose function was profoundly unclear so your teacher thought “What was I thinking? I don’t need this!” … 20 seconds later: “Why is the web site down? Ooooooooooooooooooooh!” This is the kind of mistake not to make more than once or twice, though very nearly every experienced programmer probably has done it once or twice at least.

So it doesn’t matter how clear your variable names are (e.g. url_to_get or do_not_do_this) you will eventually forget what is going on. Comments help you to avoid this, and they also allow you to write more concise, efficient code because your variable and function names don’t have to do all the heavy lifting of explanation as well!

How to comment well:

There are as many ways of commenting well as there are ways of writing code well – the point is to be clear and consistent.
You might think of adding a short comment on the end of a line of code if that line is doing something complex and not immediately obvious:

import random
random.seed(123456789) # For reproducibility

You might think of adding a one-line or multi-line comment at the start of a block of code that is achieving something specific:

# Create a new data frame to 
# hold the percentage values
# and initialise it with only
# the 'mnemonic' (i.e. GeoCode)
d_pct = pd.concat(
    [d[t]['mnemonic']], 
    axis=1, 
    keys=['mnemonic'])

You might think of using some formatting for a long section of code that forms a key stage of your analysis:

##############################
# This next section deals with
# extracting data from the 
# London Data Store and tidying
# up the values so that they work
# with pandas.
##############################

Finally, you can also use multi-line strings as a kind of comment format:

"""
=========================================================
Extract pd2-level data from the price paid medians data
=========================================================
"""

Many programmers will mix all of these different styles together, but they will do so in a consistent way: the more complex the formatting and layout of the comment, the larger the block of code to which the comment applies.

Why Style Matters

As we said at the start, style matters because it makes your code intelligible to you, and to others. For professional programmers that is incredibly important because almost no one works on their own any more: applications are too complex for one programmer to get very far. So programmers need others to be able to read and interpret the code that they’ve written.

As well, you might be asked to (or want to) go back to make changes to some code that you wrote some time ago – if you’ve not commented your code or used a consistent style you’re much more likely to break things. You might have heard of the Facebook motto “Move fast and break things” – that doesn’t refer to Facebook’s web application, it refers to paradigms.

More About Style

Unusually for a programming language, Python has a kind of style-guide called PEP 8. It even has its own web site! This is tied back to the fundamental insight that ‘code is read much more than it is written’. Which might seem counterintuitive, but we promise you that it’s true. PEP8 covers everything from how to indent your code to how to import libraries.

There’s also The Hitchiker’s Guide to Python which is modelled on Douglas Adams’ Hitchiker’s Guide to the Galaxy in tone and form. To be fair, it covers a lot more than just coding style.

More subtly, Python actually supports four fundamentally different coding paradigms (like being able to write comedies, tragedies, and dramas in general): imperative, functional, procedural, and object-oriented. We won’t get into that in Code Camp, but it’s helpful to know that these are available as you’ll definitely encounter them further into your journey.

Credits!

Contributors:

The following individuals have contributed to these teaching materials: - James Millington - Jon Reades

License

The content and structure of this teaching project itself is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 license, and the contributing source code is licensed under The MIT License.

Acknowledgements:

Supported by the Royal Geographical Society (with the Institute of British Geographers) with a Ray Y Gildea Jr Award.

Potential Dependencies:

This lesson may depend on the following libraries: None