How to write good code on first attempt

Photo by Lukas on Pexels.com

TL;DR: draw diagrams and (re-)write requirements.

If a developer has an idea about a software product or feature to be designed and/or a few minutes of thoughts on how it should be developed, he or she might feel that it’s enough, and then rush into writing some code: yeah! It’s in our (second) nature.

From my experience I know, however, that initial code written this way would be either deeply refactored later or (often easier) rewritten from scratch, and even more than once!

While sometimes this is OK (refactoring is always good development practice), I think that there is a simple way to improve our design/development efficiency when our important, yet highly complex, projects could benefit from it.

To be able to write good code on the first attempt, I think we should just use some human intermediate languages (no, not MSIL nor Java bytecode) to clarify our ideas first, rather than heading to actual programming languages and technologies already.

I’m thinking here about… diagrams and English: although programming languages seem cleaner, more logical, and offering way more clarity (for our developer minds), they often lack the amounts of expressivity, simplicity, and non-formality that initial ideas and project requirements need.

Specifically, I think these below could therefore be inserted as first steps of a development plan, such as for a new project or feature, to eventually decrease the overall effort to be spent on it:

1. Draw diagrams to represent the initial ideas.
   • Any diagram type and format is fine, don’t worry, you don’t need UML nor any fancy editor. Visio is great, but you can also go with Google Drawings, or – to me it seems the easiest while analyzing – pen and paper + your phone’s camera!
   • You can use (non-formal) pseudocode for explaining logic if it feels easier to write than drawing flowcharts.
   • For UI, do draw mocks and interaction diagrams, though. It will surely bring your focus to the end user’s experience, which is a very good thing to do as soon as possible, to prevent useless early coding.
2. Write requirements (or rewrite them, if you originally obtained them from a non-technical customer representative and you don’t like their structure.)
   • Use text, but (again) it doesn’t matter which document format you select: it can be Word, Google Docs, Pages, plain Notepad/TextEdit, or any other. And you can input the content in any way, even using voice or handwriting recognition.
   • Be concise, but do include all rules and enough use case details, as if somebody else would need to develop the system for you!
   • Add/link diagram figures (created in the first step) wherever applicable within the document.
   • Use English rather than your native language, as eventually you may want to share at least parts of the text with your customers, but moreover, because your final code would probably use it too for the names of variables, functions, and types that would eventually represent the described concepts.
3. Add functional/technical specification summary as well.
   • You don’t need to go deep: be agile, and just clear things up a little further regarding the way you would soon implement the requirements. Trust me: writing this summary down (again, with diagrams when needed), helps against the unwanted initial refactoring sessions a lot.

I’m no psychologist, but I think this process of drawing diagrams and (re-)writing requirements is like an early “rubber duck” session that some use after coding.

This does take some time and effort, and it doesn’t feel like a nice job for developers (it seems that just a few actually like to write natural language texts – that becomes clear if you read virtually any software system’s user manual), but it transforms your initial development vision so easily and so early into the correct one (that you would have otherwise obtained only after too much code refactoring), that it does worth the price!

(To give you even more material argument here, note that after you have implemented the solution and you’d want to finally deploy it, you could share parts of your requirements/specification text and diagrams as product documentation! Let’s face it: wouldn’t it be just great to already have most of that ready when you’d approach that beloved going live time? You’d just need to remove information that shouldn’t be shared with customers, add some screenshots and more examples, and you’d be done!

Moreover, although unit test names may turn into documentation when you don’t have written requirements, it could also be the other way around when you do: requirements can then serve for selecting the tests to write or for validating the ones you have written!

Finally, think about this too: having the documents ready could also help you very much if you ever need to rewrite the product to run on a different platform, or if you’re already heading to multi-platform development, especially for UI/UX code where Web, Windows, Android, macOS and iOS all have different core frameworks ready to help but also different guidelines ready to ignite stress, and input and output devices are also of many types – from voice to small and large 2D to 3D holograms and more, some of these also requiring you to adapt parts of the documents, I admit – generally, wherever you would need programming language conversions or other types of technology bridges.