The Unspoken Rules of Coding for Both Novice and Sage Developers

Many of us developers, entering our journey into the realm of software development, once held on to the dreams filled with the rush of mastering new programming languages and crafting innovative algorithms. We believed, somewhat naively, that these accomplishments alone would promote us into the esteemed ranks of invaluable developers. This mindset was a classic representation of the Dunning-Kruger effect, where beginners often underestimate the depth and complexity of their chosen field. 

However, as one gains experience, it becomes clear that simply producing code that's efficient and machine-readable is not the paramount of our desires. In this article, I aim to explore the often-overlooked principles that both budding and seasoned developers should bear in mind when penning down programs and code. May it help all of you overcome the Mount Stupid and the Valley of Despair and gain a foothold on the Slope of Enlightenment.

Two Primary Tasks of the Code

When initiating a discourse on the role of code, the most immediate thought that comes to mind is its essential function: providing specific instructions for the computer. This is undeniably the core objective of every piece of code we memorize – to achieve a predefined aim. This fundamental attribute of code is universally acknowledged, even by individuals who might stand at the farthest end of the spectrum from programming.

However, the second crucial role of code isn't as discernible and often requires a more refined perspective to truly grasp. Beyond the realm of machine-executable precision, code should be designed to be easily comprehensible and legible for the developers who engage with it — this includes the individual who wrote it as well. The topic of code readability has been a frequent subject of debate and discussion among seasoned developers and researchers alike.

Notably, some outstanding figures in the development community have dedicated significant efforts to pursue the cause of human-readable code. Among these is Donald Knuth, кenowned as the "father of the analysis of algorithms," whose works emphasize the art of computer programming; Robert C. Martin, who has been a fervent proponent of clean code principles; Jeff Atwood, a co-founder of Stack Overflow, who has always underscored the significance of making software more human-friendly, and many others. These distinguished individuals have significantly influenced the software development landscape, putting an emphasis that while our primary audience for code might be computers, we must never forget the humans who design, maintain, and evolve it.

The Importance (And Simplicity) of Clean and Structured Code

The purity and structure of code are extremely important. While it might sound like a basic thing, its significance in the realm of programming is undeniable.

Let's go into the nuances of making readable and comprehensible code. The structuring of our code is foremost among these considerations. While the underlying machinery, the computer, remains largely indifferent to code structure, processing it through various layers of compilation or interpretation depending on the programming language, humans don't have this luxury. For developers, swift navigation through code logic and extraction of information is vital.

Here are some pivotal guidelines to ensure your code remains clear:

Logical Segmentation

Always segment your code into logical blocks using functions, classes, and modules. This both aids in readability and fosters manageability. While this might seem like an obvious tip, especially to veteran developers, it's not uncommon to see even them overlook this during tight schedules, only to refactor iteratively later. Newcomers can benefit immensely from this practice: segmenting code facilitates easier modifications and error rectifications, streamlining the process of locating specific functionalities. Furthermore, structured code can mitigate replication errors.

Consistent Formatting

Embrace formatting standards. Maintain a consistent coding style which embraces indentation, bracket placements, and variable or function naming conventions pertinent to the language or library. With today's technological advancements, tools that aid in code analysis and auto-formatting are readily available. For instance, PHP developers can use 'PHP_CodeSniffer,' while those in the Go world have 'gofmt' to streamline their code.

Meaningful Naming

Allocate substantial thought when naming variables, functions, and classes. A little extra time spent during this phase can save countless moments of confusion later. Additionally, the act of pondering over naming can occasionally lead to better insights into what you're doing, potentially sparking innovative ideas regarding project execution.

Robust Error Handling

Design your code to be resilient. Consistency in error handling across a project ensures its reliability. Rather than treating errors as afterthoughts, they should be integral to the development phase.

While computers might not discern the aesthetics of code, the human developers working with it certainly do. Implementing these strategies is not just about making code 'look good' but about achieving efficiency, minimizing errors, and streamlining the development process for everyone involved.

The Double Role of Testing: Validation and Understanding

Now, let's talk about testing and what purposes it serves. When we talk about testing, it seems that it has only one goal, and the goal is obvious and that is the task of finding potential errors. But in fact, everything is much deeper here. 

The essence of testing lies not just in error detection but equally in facilitating a profound comprehension of the codebase. Many developers use tests as a kind of demo or as a book with bookmarks, and some learn hidden practices with the help of these sample codes. Thus, in this section, I would like to highlight exactly two important points:

Detecting Discrepancies

The primary and perhaps most obvious role of testing is to identify bugs, defects, and abnormal behavior within the software. A testing phase ensures that the end product aligns with its specified requirements and delivers the intended user experience.

Deepening Code Understanding

The act of making test scenarios compels developers to immerse more profoundly into the structure and functionality of their code. This isn't just a diagnostic endeavor but an introspective journey. Testing impels developers to contemplate potential usage scenarios and the interplay between various components. Furthermore, test scenarios can often double up as a user manual of sorts for newcomers to a project. These scenarios, acting as demonstrations, offer insights into the workings of specific software segments.

Documentation in Software Development

In the vast world of software development, one might imagine that code is supreme. However, the silent companion is documentation. The significance of documentation is echoed by many in the software community. Data from recent surveys and research further underlines its pivotal role.

According to Stack Overflow Developer Survey 2023, a staggering 64% of individual contributors dedicate over 30 minutes daily in search of answers or solutions, a quest that often leads them to dive into documentation. In their early stages, an overwhelming 90.36% of developers turn to technical documentation as a guiding light. As Today Was a Good Day: The Daily Life of Software Developers article reports, while it may seem that developers allocate a minimal portion of their day to documentation, the numbers translate to a noteworthy 8-10 minutes daily, or 1-2% of their time. 

However, there is a documentation dilemma. Approximately 10.3% of developers cite outdated documentation as a hindrance, causing them to spend extra time going through the mysteries of specific functionalities. This percentage isn't only attributed to documentation but also includes time lost to infrastructure issues.

How Software Engineers Use Documentation: The State Of The Practice article states that a lag is observed in the documentation refresh cycle. Software engineers often postpone updating documentation, typically doing so weeks after corresponding changes have been made to the code.  In a curious twist, it's not always the flawlessness of documentation that aids developers. In real-world scenarios, they frequently lean on incomplete or outdated documentation, deriving value and insights, showcasing the inherent utility of even imperfect documentation, reports Software Documentation: How Much is Enough? Based on the above, we can say with confidence that creating and maintaining documentation is an incredibly important aspect of work for a programmer of any level.

Conclusion

Throughout our entire article, there is a red thread of the basic principle of programming: after all, real art is not in the complexity and sophistication of the code but in its accessibility and understanding. Coding isn't just about technical feasibility; it's also about communication. Every line of code is a bridge between the developer and his colleagues and between the programmer and his future self.

By following the simple but important rules described in this article, you will be able to create products that people will want to work with, which means that your programs will be able to last a very long time and will be able to bring great benefits to users of our developments, because this is the essence of our work, right?