Do Engineers Code Differently From How They Write Documentation?

Introduction

The way engineers write code often differs significantly from how they write documentation. This difference is not just a matter of language; it reflects fundamental differences in the processes and objectives of coding and documentation. Engineers, particularly those with a background in software development, often aim to create a structured foundation in code to make future contributions easier. However, for those not immersed in coding, the reasons for these differences might not be immediately apparent. This article delves into the nuances of coding versus documentation, exploring how engineers use programming languages to build and maintain software, and the impact of this approach on their ability to write compelling and clear documentation.

Coding vs. Documentation: A Language Difference

Coding and documentation are not merely different tasks; they are fundamentally different modes of communication.

Coding: In coding, clarity and precision are vital. A programmer must ensure that the code is not only functional but also maintainable. This means the codebase should adhere to certain standards and best practices, such as being properly commented, well-organized, and modular. Well-written code is like a jigsaw puzzle where each piece fits seamlessly into the whole. This modular design facilitates future changes and maintenance, making the codebase a living document rather than a static snapshot.

Documentation: On the other hand, documentation is focused on communication. It aims to explain the purpose, behavior, and usage of code in a way that is understandable to both users and fellow developers. Documentation often uses a more natural language, often employing examples and analogies to make complex concepts more accessible. For instance, a solver for a differential equation might be documented with examples of real-world applications, such as fluid dynamics or electrical circuits, to illustrate its usefulness.

Engineers Desire a Structured Foundation

Engineers, particularly those experienced in software development, prefer a structured foundation in their code. This preference stems from a deep understanding of the value of maintainability and the importance of a clear, organized codebase.

Why Structure Matters: A structured codebase is easier to understand, modify, and extend. Engineers often work in teams, where multiple contributors need to collaborate and understand each other's code. Proper structure ensures that the code is not only functional but also readable and scalable. This structure enables new engineers to quickly understand the existing codebase, reducing the cognitive load and accelerating the learning curve.

Example: Structured Code in Excel: Consider Excel as an example. While it is a powerful tool, its limitations in terms of structured coding can be significant. An experienced engineer might write a script or macro to perform complex data processing. In such cases, the script would be organized into clear, separate functions and modules, each with its purpose and documentation. This approach makes it easier for others to understand and modify the script, ensuring that it remains maintainable over time.

Metaphorical Thinking and Top-Down Control

Metaphorical thinking and top-down control are powerful tools that engineers use to manage and organize their code. These techniques help them to break down complex problems into manageable components, making the coding process more intuitive and straightforward.

Metaphorical Thinking: Engineers often use analogies and metaphors to conceptualize and explain complex systems. For example, a video game can be thought of as a series of interconnected systems, each with its own set of rules and behaviors. By structuring code in a way that mirrors these systems, engineers can make the codebase more intuitive and easier to maintain.

Top-Down Control: Top-down control involves breaking down a large problem into smaller, more manageable parts. This approach allows engineers to focus on one aspect of the problem at a time, reducing the cognitive load and making the coding process more efficient. Top-down control is particularly useful when working with large projects, as it helps to ensure that each part of the system is properly integrated.

Real-World Examples and Demos

The design of a video game using Excel, while challenging, can be an excellent example of how engineers might leverage Excel to achieve their goals. While Excel is primarily a spreadsheet application, it can be used to create complex models and simulations. An engineer could develop a prototype of a video game using Excel, with each cell representing a different aspect of the game’s mechanics. By using functions and formulas to represent these mechanics, the engineer can create a functional and maintainable prototype.

Real-World Example: For instance, an engineer working on a turn-based strategy game using Excel might create a spreadsheet where each row represents a player, and each column represents a different aspect of the player’s resources (e.g., health, money, units). Functions and formulas can then be used to simulate the game’s mechanics, such as combat, resource management, and strategic decisions. By documenting each function and cell in the spreadsheet, the engineer can ensure that fellow developers and future contributors can understand and modify the game logic as needed.

Conclusion: The differences between coding and documentation are significant and reflect the distinct goals and requirements of each task. Engineers strive to create a structured foundation in their code, using techniques like metaphorical thinking and top-down control to enhance maintainability and understandability. Understanding these differences can help developers and non-developers alike appreciate the value of well-structured code and the importance of clear, detailed documentation.

Keywords: programming, documentation, engineering, coding styles, software development