{"id":83,"date":"2024-03-05T18:54:25","date_gmt":"2024-03-05T18:54:25","guid":{"rendered":"https:\/\/permutationcity.co.uk\/bp\/?p=83"},"modified":"2024-07-27T08:53:14","modified_gmt":"2024-07-27T08:53:14","slug":"the-elements-of-programming-style","status":"publish","type":"post","link":"https:\/\/permutationcity.co.uk\/bp\/2024\/03\/05\/the-elements-of-programming-style\/","title":{"rendered":"Historic programming style"},"content":{"rendered":"\n

While researching one of my recent post I came across a reference to\nThe Elements of Programming Style<\/a>.\nIt’s a study of programming style and it was first published 50 year ago.\nMy dad recognised the book and he remembers when you had to make programs using punched cards!<\/p>\n\n\n\n

Despite it’s age a lot of it’s recommendations still seemed to have merit today.\nI managed to get hold of a copy and decided to read through to get the context for these rules.<\/p>\n\n\n\n

Full disclosure, I did a lot of skimming. It’s examples are in Fortran<\/a> and PL\/1<\/a> and… it turns out that I don’t like these languages. Fortran doesn’t have structured programming<\/a> and all it’s flow control is done using goto<\/code>. It doesn’t even have normal comparison operators and uses .gt.<\/code> rather than <<\/code>. We have progressed since then.<\/p>\n\n\n\n

Fortunately it’s the lessons I want to look at and there is a\nsummary<\/a>.<\/p>\n\n\n\n

Be clear<\/h2>\n\n\n\n

1. Write clearly \u2013 don’t be too clever.
2. Say what you mean, simply and directly.
5. Write clearly \u2013 don’t sacrifice clarity for efficiency.
8. Parenthesize to avoid ambiguity.
9. Choose variable names that won’t be confused.
52. Use variable names that mean something.
53. Use statement labels that mean something.
54. Format a program to help the reader understand it. <\/p>\n\n\n\n

All of these made sense then and they still make sense now.\nThe sample code didn’t follow my naming guidelines<\/a>\nbut there may well have been identifier length limits at that point.<\/p>\n\n\n\n

6. Let the machine do the dirty work. <\/p>\n\n\n\n

This sounds weird out of context.\nIn the book it’s encouraging you to let the compiler do conversion and setup work rather than doing it manually.\nWe can now expect our compilers to do far more during the build.<\/p>\n\n\n\n

11. If a logical expression is hard to understand, try transforming it.
51. Don’t comment bad code \u2013 rewrite it. <\/p>\n\n\n\n

I think this is sensible advice to consider today.\nIf you are using expressions that seem fundamentally hard to understand, do something about it.\nYou could add a long comment trying to explain them but can you do something better?\nSplitting a single expression into multiple expressions assigned to temporary variables might help.\nMaybe you can look at the expression from a different angle that easier to understand.\nYou should make your code easy to understand to help the next person (who may be future you).<\/p>\n\n\n\n

Function usage<\/h2>\n\n\n\n

3. Use library functions whenever feasible.
7. Replace repetitive expressions by calls to common functions.
14. Modularize. Use procedures and functions. <\/p>\n\n\n\n

This is mostly an assumption nowadays.\nWhen this book was published some people will have been adjusting to the idea of function calls.<\/p>\n\n\n\n

44. Don’t strain to re-use code; reorganize instead. <\/p>\n\n\n\n

This is about functions that are trying to do too much.\nIf you refactor so each function concentrates on doing just one thing then each function can be more easily reused.<\/p>\n\n\n\n

Variable initialisation<\/h2>\n\n\n\n

4. Avoid too many temporary variables.
27. Make sure all variables are initialized before use. <\/p>\n\n\n\n

Now we can delay the creating a variable until just before it is needed and initialise it immediately.<\/p>\n\n\n\n

Flow control<\/h2>\n\n\n\n

10. Avoid unnecessary branches.
15. Avoid gotos completely if you can keep the program readable.
31. Take care to branch the right way on equality.
32. Be careful if a loop exits to the same place from the middle and the bottom. <\/p>\n\n\n\n

These all seem to be associated with the lack of structure programming.\nI hope you’re not using goto<\/code> in your code nowadays.<\/p>\n\n\n\n

18. Use recursive procedures for recursively-defined data structures. <\/p>\n\n\n\n

Maybe this required emphasis because of Fortran’s limitation.<\/p>\n\n\n\n

Bugs breed bugs<\/h2>\n\n\n\n

16. Don’t patch bad code \u2013 rewrite it. <\/p>\n\n\n\n

This one is interesting.\nI’ve certainly come across bits of code that seemed cursed.\nThey regularly had bugs, got fixed and then had more bugs later on.\nThat could be code that wasn’t written well in the first place so it has many bugs.\nThat could be code isn’t a good fit for the problem so that bugs keep being made.\nGetting rid of everything and starting again might be better than patching something with problems.\nOn the other hand you might just end up with new flawed code.\nI’d say this is good advice to keep in mind but not necessarily to follow every time.<\/p>\n\n\n\n

28. Don’t stop at one bug. <\/p>\n\n\n\n

Don’t just assume your code must be working now. Make sure it is.<\/p>\n\n\n\n

29. Use debugging compilers. <\/p>\n\n\n\n

Being able to debug is good.<\/p>\n\n\n\n

Testing<\/h2>\n\n\n\n

17. Write and test a big program in small pieces. <\/p>\n\n\n\n

I think most people are working on larger programs nowadays.\nWe wouldn’t try and write the everything and leave all the testing until the end.\nHowever we might still try and finish a task in one go and leave the testing until the end.\nWriting small pieces and testing as you go is often better.\nYou have a better idea of what each piece needs and you’re less likely to miss edge cases.\nIf you’re still prototyping<\/a>\nyou could be more relaxed about this as you will have another chance to revisit testing later.<\/p>\n\n\n\n

33. Make sure your code does “nothing” gracefully.
34. Test programs at their boundary values. <\/p>\n\n\n\n

Remember to test code with the different values can accept, not just the ones you want to get.<\/p>\n\n\n\n

35. Check some answers by hand. <\/p>\n\n\n\n

I don’t think will always be possible.\nMaybe most programs were just much simpler back then.\nIt is good to check some answers using another method.\nThat might be by hand or it might be using a different, perhaps slower algorithm.\nI sometimes write my initial code with the slow but obviously correct algorithm.\nThat algorithm then becomes the basis for my testing code when the main algorithm is upgraded to something faster\nbut less certain.<\/p>\n\n\n\n

Errors<\/h2>\n\n\n\n

30. Watch out for off-by-one errors. <\/p>\n\n\n\n

As true now as it was then.\nFor-loops were a common source of these.\nNow we can often re-write these to iterate directly over a collection which\navoids any comparison that could go wrong.\nWriting code that just can’t have that bug is the safer option.<\/p>\n\n\n\n

36. 10.0 times 0.1 is hardly ever 1.0.
37. 7\/8 is zero while 7.0\/8.0 is not zero.
38. Don’t compare floating point numbers solely for equality. <\/p>\n\n\n\n

I don’t come across people making these mistakes too often.\nIt’s certainly something I keep in mind for floating point numbers.<\/p>\n\n\n\n

Appropriate optimisation<\/h2>\n\n\n\n

39. Make it right before you make it faster.
40. Make it fail-safe before you make it faster.
41. Make it clear before you make it faster.
42. Don’t sacrifice clarity for small gains in efficiency. <\/p>\n\n\n\n

It is interesting to see how much comes before optimisation.\nThink about how much slower machines were back then.\nEven with that he was recommending that optimisation comes last.<\/p>\n\n\n\n

43. Let your compiler do the simple optimizations.
45. Make sure special cases are truly special.
46. Keep it simple to make it faster.
47. Don’t diddle code to make it faster \u2013 find a better algorithm. <\/p>\n\n\n\n

We often don’t think about how much our compilers do for us today.\nWith a normal compiler your code is regularly transformed into something much more efficient.\nFunctions are inlined, expressions are pre-calculated, it happens every time we hit build.<\/p>\n\n\n\n

You can spend ages worrying over fine details but the overall algorithm often has the biggest effect.\nIf you have the right algorithm your code can be many orders of magnitude faster.\nFirst make sure you’re getting the right answers then make sure you have the best algorithm.<\/p>\n\n\n\n

48. Instrument your programs. Measure before making efficiency changes. <\/p>\n\n\n\n

I’ve posted about optimisation before<\/a> and how important it is to pick your targets. You may think you know what’s slowing down your code but it’s much better to know. Don’t, say, spend time optimising a calculation if the real problem is doing the same calculation many times.<\/p>\n\n\n\n

Think about the data<\/h2>\n\n\n\n

12. Choose a data representation that makes the program simple.
21. Terminate input by end-of-file marker, not by count. <\/p>\n\n\n\n

We have a lot of file standards<\/a> that can make our lives easier today. There is normal a library that can fairly easily transform your local data for file storage or network traffic.<\/p>\n\n\n\n

Comments<\/h2>\n\n\n\n

13. Write first in easy-to-understand pseudo language; then translate into whatever language you have to use. <\/p>\n\n\n\n

I don’t think is so relevant nowadays.\nOur languages and libraries are able to more things directly now.\nI do still sometimes rough out the behaviour of a function with comments before writing the real code.<\/p>\n\n\n\n

49. Make sure comments and code agree. <\/p>\n\n\n\n

While this is obvious it is something to watch for.\nI’ve discussed code reviews<\/a>\nbefore as a way of catching mistakes.\nIf someone has changed the code make sure the comment has been updated if necessary.<\/p>\n\n\n\n

50. Don’t just echo the code with comments \u2013 make every comment count.
56. Don’t over-comment. <\/p>\n\n\n\n

These two lessons seem to belong together given the details in the book. If your comments are just a slightly different wording of the code then you aren’t adding value. I do<\/em> like to see comments that tell me the “why” behind the code.<\/p>\n\n\n\n

Input and output<\/h2>\n\n\n\n

19. Test input for plausibility and validity.
20. Make sure input doesn’t violate the limits of the program.
22. Identify bad input; recover if possible.
23. Make input easy to prepare and output self-explanatory.
24. Use uniform input formats.
25. Make input easy to proofread.
26. Use self-identifying input. Allow defaults. Echo both on output.
55. Document your data layouts. <\/p>\n\n\n\n

I think this will have been written exclusively with the console and batch processing in mind.\nIt’s always worth considering that there may be problems with incoming data.\nJust because the data is meant to look a certain way doesn’t mean it will.<\/p>\n\n\n\n

I’d highlight a problem with recovery mechanisms.\nThey can end up hiding bugs elsewhere in the system.\nIf something has gone wrong this should be obvious to the developers.\nYou want to know if there’s a problem so you can fix it.\nIf the user thinks they’re using a particular setting it shouldn’t just silently switch to a default.<\/p>\n\n\n\n

On balance<\/h2>\n\n\n\n

I don’t think that was bad for a 50 year old book.\nWhile I don’t want to read any more Fortran the lessons are often still relevant.\nGiven how much less powerful their computers they still thought that getting it right and being clear\nwas better than worrying about every clock cycle.<\/p>\n","protected":false},"excerpt":{"rendered":"

While researching one of my recent post I came across a reference to The Elements of Programming Style. It’s a study of programming style and it was first published 50 year ago. My dad recognised the book and he remembers when you had to make programs using punched cards! Despite it’s age a lot of […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_import_markdown_pro_load_document_selector":0,"_import_markdown_pro_submit_text_textarea":"","footnotes":""},"categories":[34],"tags":[20,7,8,13],"class_list":["post-83","post","type-post","status-publish","format-standard","hentry","category-review","tag-books","tag-performance","tag-standards","tag-testing"],"_links":{"self":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/83","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/comments?post=83"}],"version-history":[{"count":3,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/83\/revisions"}],"predecessor-version":[{"id":199,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/83\/revisions\/199"}],"wp:attachment":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/media?parent=83"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/categories?post=83"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/tags?post=83"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}