Deeds not words

It’s about time I got on and wrote an editorial. I have been making excuses for well over five years now! Well, I say that, and I am sure our readers all agree. It’s much easier to say something than actually get on with it. I have previously considered why it can be important to talk things through as a team before rushing in to solve a problem or write code [ Buontempo15 ]. Charles Tolman’s recent mini-series also reminded us that changing code to speed it up, without careful measuring and thinking first, can make problems worse [ Tolman17 ]. However, “ There is a time for everything, and a season for every activity under the heavens... A time to search and a time to give up. A time to keep and a time to throw away. ” [Ecclesiastes 3:1]. There is a time for meetings and a time for coding. There is a time for words and a time for deeds.

This year sees the centenary of women being given the vote in the UK, a select few women to be fair. The internet tells me “Parliament passed an act granting the vote to women over the age of 30 who were householders, the wives of householders, occupiers of property with an annual rent of £5, and graduates of British universities.” [ Wikipedia-a ]. The internet also tells me women could originally vote, or at least were not explicitly excluded, but the Reform Act stopped this. The act also stopped most men from voting. Landownership and occupation, and gender, became criteria for enfranchisement. During the First World War, many women took over roles usually performed by men, bringing the question of voting to the fore. War often brings about unexpected changes, from technological innovations, such as computers, to social reform! “There is a time for war and a time for peace.” [Ecclesiastes 3:8]. I’m not suggesting war is a good thing, rather that the effects are interesting and unexpected. Who would have predicted a war would start conversions about women’s suffrage or voting? Calling members of the Women’s Social and Political Union ‘suffragettes’ seems to have been a deliberate insult [ Oxford Dictionaries ], adding the diminutive ette to suffrage to subtract from the movement. The word now sticks and the original connotation is lost. Words do matter, but sometimes deeds are more important or more likely to get results. I believe “Deeds not words” became one of the suffragettes’ slogans while campaigning via hunger strikes, riots and similar [ Parliament.uk ]. Do you have a motto or slogan? After a long discussion about a comment that did not match some code in a role a long while ago, I used “Delete the comment and fix the code” as a motto for a while. I still maintain this is a worthwhile life goal. It’s not as extreme as starting riots, but a form of direct action is sometimes required. There are times when words are not enough.

Words come in many forms, sometimes written, sometimes in a telco, sometimes face to face, or even via webcasts. Let’s talk about meetings. How many of you get stuck in meetings, of increasing length and frequency, nearer a release in order to talk about the impending doom? Or success? Do you have lots of meetings before you even begin a software project? It can be frustrating to sit through a meeting talking about software without having a chance to experiment and explore first, so that decisions and action points can be based on knowledge rather than speculation. Speculating is important, but does not require a meeting, rather a gathering to devise, plot and dream. Of course, you need to meet up and share what you have found out. You do need meetings, but not all the time! I am stuck in a form of personal meeting madness. I even visited Chichester cathedral on holiday the other week and was shocked to see a large gathering in the nave. It turned out to be a Women’s Institute and flower arrangers’ meeting, plotting a flower festival later in the year. I have no idea how or why I end up in so many meetings. Or why so many of them go on for so long. Wandering into the flower arranger’s meeting was an absurdness that amused me.

Assuming you manage to sanitise your meetings, keeping them on time and on topic, keeping irrelevant chatter for the water cooler or the pub, what other ways do words get in the way of deeds? A perennial problem of documentation persists for many programmers. This is related to the tension over meetings that has been tormenting me recently. Managers and product owners want to be kept up to date with the current state of play, and understand what choices have been made, so they can steer development and keep things on track. Developers also want to write working software, but if they spend all day in meetings they can’t do their job. If the developers refuse to attend meetings, the managers can’t do their job. You can find a balance point to keep everyone happy and the project moving along, but it takes work. Similarly, managers tend to request documentation. They don’t want to have to wade through thousands of lines of code to understand what a product does or how it works. A developer, on the other hand, might just break down in tears if confronted with fifty or so pages of documentation ‘summarising’ how 50 lines of code works, particularly if they can’t find the code because the latest version isn’t in version control. What gives?

Automatic generation of documentation seems like the best way to solve this problem. Most of us have encountered Doxygen at some point [ Doxygen ]. It can be really useful. However, there is no substitute for a short readme file, showing how to build and run the code. Automatically generated documentation is very unlikely to include this. I have been working with Chris Simons, preparing a workshop for this year’s ACCU conference [ ACCU18 ]. We will demonstrate how to use a Java framework for evolutionary computing, which Chris has written about previously [ Ramirez17 ]. The framework is very powerful; however, the main documentation consists of a 65 page pdf, replete with UML diagrams and worked examples and there is a doxygen generated webpage. To be fair, there are notes on how to build and run the examples! Despite all this, I am none the wiser as to what BLXAlphaCrossover is [ Sourceforge ]. Obviously, it is a crossover operator, that’s what the X means (you guessed that, right?), using an alpha (a parameter I presume). A relatively thorough internet search suggests BL stands for ‘blended’. I think it amounts to subtraction and multiplying and I promise I will know by the conference. I shall look at the source code. There is documentation. It has diagrams. It shows me how to use the framework. It includes BLXAlphaCrossover but doesn’t tell me what it does, rather what it derives from and its methods. The details themselves are in the code. No matter how thorough you have been, sometimes only the code itself tells the whole story. 97 Things Every Programmer Should Know [ Henney10 ] points this out. Documentation may tell us what code is supposed to do, but the code tells us what it actually does. A design document may tell us the intentions, but not what actually happened when to code was written. Sometimes you need to try out the code, even trying a few scratch refactors [ Feathers04 ], to understand how it works. Extract methods, move variables, change access levels to see what happens. Sitting in a presentation watching someone point at a UML diagram is no substitute. Reading a pdf or wiki is no substitute. You need to get your hands dirty to fully understand.

Once you have your hands on the code you can find out all kinds of things. When the documentation doesn’t show you exactly what a function is up to, there is sometimes a comment, which fails to make it to the doxygen output, referring to an academic paper. Many people regard comments as documentation. They can be, though they can get out of sync with the code. A readme showing me how to run the examples would not explain the minutiae of details concerning how to approach combining real values from two parent solutions in a genetic algorithm (the blending alluded to previously).Having to dig inside source code to find what it all means renders a long pdf or word document somewhat superfluous. Another trick is searching the internet for the comments you find in a library. On many occasions, the comment turns up with other source code, along with better documentation or even unit tests. Never fix a comment – even if it contains a spelling mistake. You are destroying forensic evidence. You will regret this. I know I suggested, “Delete the comment and fix the code" earlier. There is a time and a place.

Documentation after the fact is important. Different people, with differing roles, have different requirements. It is important to keep everyone happy. You may disagree, and might think that’s why I keep getting stuck in long meetings. We’ll save that for a pub discussion. Don’t be shy about automatically generating your documentation if someone insists they need it. Do provide me with a small file showing how to get up and running quickly though! Please! Now, step back in time. What do you expect to see in writing before you start on a greenfield project? A two-hundred-page upfront specification, along with a Gantt chart? User stories, along with the stick figures? Some BDD-style user requirements? Millions of meeting invites to flesh out the pipe dream? A vague mission statement and contact details for product owners and the rest of the team? A list of allowed libraries or programming languages? An invitation to a training session on how to use your workstation safely, including how to sit on a chair? What do you need to know in order to get things done? What is the one thing you cannot do without, your sin qua non for success? [ Wikipedia-b ]. I need to know how we will verify or test a solution is working. You may have different priorities. That’s ok.

If you are part of a team, you might find other people have other needs and assumptions. I alluded to the tension between people with different roles earlier. A manager in need of useful, high level documentation and a dev in need of a sane development pipeline might be trying to build the same product, but might have different assessments of how to achieve this in an efficient manner. When people with different roles don’t understand each other, the tension can lead to conflict and all-out war. Or lots of long meetings. Alexei Sayle, in ‘Thatcher stole my trousers’ [ Sayle16 ], claims “No good ever came from meetings. The Russian revolution was just a meeting that got out of hand." One viewpoint. How can you learn to communicate as a team and build up consensus? Sometimes pairing on a task can help. If you can demonstrate why it takes several days to build code to replicate what a spreadsheet built in an hour does, you might get some understanding. If you go with your manager to the senior managers’ meeting, just once, you might realise why there is an insistence on a Gantt chart or spreadsheet. If you sit with your testers or support team, you might realise why they want documentation including a list of error messages. If you sit with one of your colleagues and pair program a prototype with them, you will also learn lots. Building a prototype gives you something concrete to discuss in the next meeting. Deeds, not words, can help you make progress. If you intended to throw away the prototype and find it ends up being the basis for a large production system, you have a different problem.

If you are going round and round in circles, never writing an editorial, an article for Overload or even code, remember Poincaré’s recurrence theorem: “certain systems will, after a sufficiently long but finite time, return to a state very close to the initial state” [ Wikipedia-c ]. This applies to mechanical systems under some specific conditions, but can be misappropriated to apply to software development. If you start with lots of meetings, you will end with lots of meetings. If you need an algorithm to do something specific, someone has probably already written it. If you rewrite a system, because the original code was horrific, your re-write will eventually be re-written. If you attend training on how to sit on a chair, you will probably end up having further similar training.

What has been will be again,
what has been done will be done again;
there is nothing new under the sun.
~ Ecclesiastes 1:9

References

[ACCU18] ACCU Conference 2018: https://conference.accu.org/2018/sessions.html#XSimplytheBestOptimisingwithanEvolutionaryComputingFramework

[Buontempo15] Buontempo, Frances (2015) ‘A little more conversation, a little less action’ Overload , 23(127):2–3, June 2015. https://accu.org/index.php/journals/2106

[Doxygen] Doxygen http://www.doxygen.org

[Feathers04] Working Effectively with Legacy Code , Michael Feathers, Prentice Hall 2004

[Henney10] Henney, Kevlin (ed.) (2010) 97 Things Every Programmer Should Know http://programmer.97things.oreilly.com/wiki/index.php/Only_the_Code_Tells_the_Truth O’Reilly

[Oxford Dictionaries] ‘Woman or suffragette’ https://blog.oxforddictionaries.com/2013/05/02/woman-or-suffragette/

[Parliament.uk] ‘Deeds not words’ http://www.parliament.uk/about/living-heritage/transformingsociety/electionsvoting/womenvote/overview/deedsnotwords/

[Ramirez17] ‘Evolutionary Computing Frameworks for Optimisation’, Overload #142 – December 2017, Aurora Ramírez and Chris Simons https://accu.org/index.php/journals/2444

[Sayle16] Sayle, Alexi (2016) ‘Thatcher stole my trousers’, 2016 Bloomsbury Circus

[Sourceforge] BLXAlphaCrossover: http://jclec.sourceforge.net/data/jclec4-classification-doc/net/sf/jclec/realarray/rec/BLXAlphaCrossover.html

[Tolman17] Tolman, Charles (2017) ‘A Design Example’ Overload #142 – December 2017 https://accu.org/index.php/journals/2447

[Wikipedia-a] ‘Women’s suffrage in the United Kingdom’ https://en.wikipedia.org/wiki/Women%27s_suffrage_in_the_United_Kingdom

[Wikipedia-b] Sine qua non: https://en.wikipedia.org/wiki/Sine_qua_non

[Wikipedia-c] Poincaré recurrence theorem: https://en.wikipedia.org/wiki/Poincar%C3%A9_recurrence_theorem