[Tweets]

24/11/2017 5:11pm
RT @BristolRobotLab: APPLY NOW: Opportunity to join the FARSCOPE 4 year PhD programme in 2018, based here at the BRL [LINK]
24/11/2017 5:11pm
RT @ProfCompMod: Good news from @unisouthampton: Three cups of coffee a day 'may have health benefits' [LINK] @NGCM_Soton
20/11/2017 12:10pm
How is information utilised in robot swarms? "The Information-Cost-Reward framework for understanding #robot #swarm[LINK]
15/11/2017 10:12pm
DVLA asks me to join the NHS Organ Donor Register after I ordered a form to get my driving license. They already kn… [LINK]

[Coding for tomorrow: Why is good code important?]

Added on 27/01/2017
Tags: web :: Objective-C :: Matlab :: Java :: C++ :: ActionScript


"Why should I care about how my code is written, as long as it works?" I have met with this attitude many times, especially around academics, but also among software developers. We are often faced with deadlines that demand the results of our simulation or software. The code behind the applications remains forever hidden, it is not formally assessed, and therefore might seem unimportant. However, I will argue here that well-structured and well-written code not only saves time on a project, it also helps you to invest your time in a way that is meaningful for your future work.

Design vs coding

The first important topic is that of design versus coding. By "design" I mean the time before we start programming, during which we think about how data will be stored and retrieved, what classes (in object-oriented programming) or modules (in functional programming) will be used and how they will relate to each other, what kind of actions will the user need to perform to get from A to B, etc. This kind of design is usually performed by a coder with the help of diagrams, such as flowcharts, statecharts, class diagrams, etc. (see the image below). When done correctly, it provides an overview of how an application or a simulation will work and how it will be built. More importantly, functionality can easily be redesigned and discussed among programmers, as well as with people who know nothing about coding.

An example of a flowchart, statechart and a class diagram

Code implementation takes much longer than the design stage. For example, it is much faster to draw two boxes for "Text file" and "Simulation engine" and an arrow between them to signify that the simulation engine writes data into a text file, than actually implementing this in a programming language. This is why as much time as possible should be spent on the design stage. Furthermore, designing code this way can help you to keep an eye on "the bigger picture", without being distracted by particular implementation details. If the design stage is rushed through, or even worse, if it never happens at all, it is almost guaranteed that time will be lost for creating bad code that will need to be scrapped or rewritten later. For example, imagine that when implementing another part of the simulation, we realise that we actually need to store our data in a database. All the time spent writing code for text file storage will be lost.

Good coding practises

The second important point to consider is coding practises. It is possible that even if we take good care when designing our software, something will need to change or be extended along the line. Therefore, program code should always be written as clearly as possible and be well-organised. For example, the following can help:

  • Well-structured coding project: Related classes and modules should be kept together in a meaningful way in packages, namespaces, etc. For instance, classes or modules that are responsible for data storage should be clearly distinguished from those that provide user interface.
  • Naming conventions: There are no universal naming conventions that need to be followed, but we need to be consistent in a single project. Naming variables sensibly and with lower-case letters, starting class names with upper-case letters, starting pointer names with a 'p', or capitalising names of constants are just a few examples of conventions that can be maintained.
  • Good documentation: There are two types of documentation that are equally important. Commenting code is crucial to help others and yourself to understand the code that has been written. This could include a text block on top of your class, module or function to explain what it does, comments next to variable definitions, or comments inside functions that explain specific lines of code. The second type of documentation is more 'high-level' and ties back to the design stage. If you have created a class diagram, make sure to include it with the project and update it when something in the code changes. If there is a complicated way of gathering or displaying data, make sure to document it in a text file somewhere. In other words, write down or draw anything that could be unclear later on.

Good versus bad coding practises

Good coding practises can save an incredible amount of time and stress when it comes to altering, reusing and extending code. There are few things more annoying or stressful for a developer than having to work with code that cannot be understood even after being read five times. Some coders seem to be under the impression that spending the extra time to properly document or structure code is not as crucial when working alone or with a small group of people, where any questions can be simply answered by the person who wrote a particular piece of the software. I would like to challenge this attitude in three ways:

  • 1. You never know when the person who wrote the code will not be available anymore to answer questions. If there is no written record of how their code works, who will you turn to?
  • 2. You never know whether the size of your team will grow later on. Writing documentation at a later stage of the project, so that a larger team can manage and understand the software, can quickly become a nightmare that takes away precious resources.
  • 3. You might want to use your code in one, five, or N years after you have written it. You simply cannot be certain that this will never happen. This applies when working in a team or when working alone. If you don't help yourself understand your code now, it will be very difficult to understand it later.


I have found it a good idea, when working in a team, to designate a person who can keep an eye on common code. For example, the person could check every week or every month if the agreed conventions are being applied, if documentation makes sense, etc., and ask relevant people to put more work in if this is not the case.

Summing up

In my opinion, the following is a good way of thinking about code, be it for a scientific simulation, for a commercial software project, or even for a small script that does something useful: Take care of how you write and document. Think of your code as an investment for the future. You are inventing a unique piece of functionality right now, so make sure that you can always use it when you need it later. In other words, code not just for today, but also for tomorrow.



{Please enable JavaScript in order to post comments}

[Blog]

Robot swarms in action

Watch e-puck robots collect resources and bring them back to base. While the previous simulation work helped us to learn a lot about the...

[read full]

How to compile code for e-puck robots on your computer

Compiling code natively on e-puck robots or cross-compiling on your computer can be very tedious. Luckily, there is a third option:...

[read full]

Coding for tomorrow: Why is good code important?

"Why should I care about how my code is written, as long as it works?" I will argue here that well-structured and well-written code not...

[read full]

How Coding in Python Might Be Bad For You

7 reasons why coding in Python is like writing a really bad essay and getting away with it

[read full]