Why should we write programs like building a house?

Leslie lanbert is a computer scientist who specializes in Distributed Systems, temporal logic, and parallel algorithms. He is a member of the National Emy of engineering and National Emy of sciences. He is a bachelor of mathematics at the Massachusetts Institute of Technology and has earned his master and doctorate degree at Brandeis University. He works for the Microsoft Research Institute.

Prior to building a brick or nailing a nail, the architect will make a detailed plan. Programmers or software engineers do not. Is this the reason that the House seldom falls down and the program Often crashes?

The blueprint ensures that the building designed by the architect is built as planned. "Built" not only means not to collapse, but also means to achieve the functions required by the owner. Architects and their customers communicate with each other through blueprints before starting construction to understand what they will create.

However, few programmers may sketch a simple sketch to illustrate how their programs will look before coding.

Most Programmers think that doing anything without code is a waste of time. Thinking does not produce code. If you don't think about it, you can start coding. It only produces bad code. We should understand what functions these codes need to implement. It is difficult to think about understanding. Borrow the following sentence from the cartoonist dick guineden:

Writing is an instinctive way to let you know how sad your thoughts are.

The blueprint gives us a clear picture of the building we plan to build. Before writing a piece of code, we should first write a blueprint. A software blueprint is called a technical manual.

There are too many excuses to say that writing a technical manual is just a waste of time. For example, a technical manual is useless and we cannot use it to generate code. This is like saying that architects should not draw blueprints, because they eventually need contractors to build the house. Another argument against writing a technical manual can be refuted using the blueprint example.

Some programmers argue that it is useless to compare the blueprint with the Technical Manual. After all, the program is not a building. They think that it is much harder to overturn a wall than to change code, so the program blueprint is not necessary.

Error! Change the codeDifficultEspecially if we don't want the program to be defective.

Recently, I need to modify some code that is not written by me to add a small function to the program. To complete this operation, you need to understand an interface. I spent a whole day using a debugger to study what the interface was doing-it would take five minutes to read the Technical Manual. To avoid import defects, I have to figure out the results after each modification. This problem becomes more difficult because there is no technical manual. I have to read thousands of lines of code. It took me several days to figure out how to modify as few codes as possible. Finally, it took me a week to add and modify 180 lines of code. This is only a small change to this program.

Modifying code is only a small task. Most of the Code has been written more than a decade ago. Even though I hardly remember what the code is, it is quite easy to modify it. By reading the technical manual I wrote, it is easy to find the place I want to modify. Despite the heavy workload of these modifications and the impact on other code, I can fix it quickly.

What is my technical manual? It is generally considered to be something written in formal technical languages. But writing formal technical instructions only needs to be done occasionally. If we just build a tool shed, we do not need to draw the blueprint required by the skyscraper. For most software, we do not need formal technical manuals. However, even if you write a small program, you can't help but write technical instructions. Otherwise, you just need to build a tool shed without any plans.

In these days, the programs I write are usually only small houses, not skyscrapers. I usually write down the implementation methods of each algorithm. Most algorithms are very simple and can be clearly written in just one or two sentences. Sometimes it is necessary to make a good idea about how an algorithm works, and it may take a few pages or pages to make it clear. I have a simple principle: the Technical Manual should be clear about everything the algorithm users need to know. After the code is written and compiled, it is estimated that no one will read it again.

Once I understand the purpose of a piece of code, it is easy to write code. But some codes do not. They require complicated algorithms. To make an algorithm work, you need to carefully think about it. Therefore, you need a technical manual.

Most of the technical manuals I have written are informal. Occasionally, a piece of code is exquisite and critical, which requires formal writing. To ensure accuracy, you even need to use the Writing Tool to check carefully. Such formal events have been around for dozens of times in the past decade.

For designers of complex systems, a formal technical manual is necessary, just like a blueprint for a skyscraper. But few engineers write technical instructions because they don't have time to learn how to do it well, and they don't teach it at school. Some schools teach technical instruction terms, but seldom teach how to apply them in practical work. If you don't even draw a blueprint for a tool shed, how can you draw a blueprint for a skyscraper?

Practice is required to learn to write technical manuals. There are no simple rules to ensure that you write a good technical manual. However, you should avoid using code. Understanding code through code is a bad thing. Architects do not use bricks to create blueprints.

The key to understanding a complex thing is abstraction, which means that the technical description is higher than the code. The simplest and most accurate language is mathematics, which is taught in elementary mathematics: Set, function, and simple logic. However, most formal technical manuals use languages that are not in elementary mathematics classes, such as type. However, the more away from the language of simple mathematics, the more difficult we are to understand a complex program or system.

Whether using formal technical manuals for complex systems or informal technical manuals for simple code, writing technical manuals will improve the quality of our code. It helps us understand what we are doing and reduce errors. Of course, even if you write a technical manual, your program will not crash. We still need to use other existing methods and tools to reduce code defects.

Thinking does not guarantee that we will not make mistakes. However, if you don't think about it, you will definitely make mistakes.