Programmers should comment

If the architect's final product is architecture, then the final product of the programmer and the software engineer will be the software. Before the actual commencement, the architect will master every detail of the building, and it will be reflected in the blueprint. But programmers and software engineers are not the same. This may be why the house rarely collapses, and the software often crashes?

Writing code and writing articles, to some extent, is related to the need for logic, architecture, as concise as possible. The creator's timetable and the manager's timetable are not the same, coding and writing articles, are a lonely and can not be disturbed by the process, facing the screen, is a fight with their own.

Similarly, if the architect's final finished product is architecture, then the final product of the programmer and the software engineer is the software. Before the actual commencement, the architect will present every detail of the building in the blueprint. Just programmers and software engineers don't do that. Perhaps that is why houses rarely collapse, and software often crashes?

Blueprints will help architects determine that their designs are feasible. "Feasible" is not just a guarantee of not collapsing, it also means that the building can achieve the intended service to people's goals. A client or developer is a blueprint to understand what a designer thinks and what he is going to do.

By contrast, few programmers have even a rough frame before they start writing code.

Most programmers think that everything that can't produce code directly is meaningless. Thinking doesn't translate directly into code, but it doesn't make sense to start rushing code words without a whole frame. Before programmers start writing code, they should fully understand the functionality that the code ultimately implements. The process of understanding naturally requires thinking, and writing down the process of thinking is a time-consuming thing for programmers.

But cartoonist Dick Guindon was once:

Writing is the best way to find out how bad your ideas are.

The blueprint helps us understand the architecture of the building, and again, we need a similar "blueprint", the "Annotation" (specification), before we start crackling the code.

"Annotations" cannot produce code directly, so many programmers overlook it. But there is no "annotation", which is written directly, as if the building contractor had no designer drawings to go straight.

It is also said that it is unreasonable to compare programmers to architects. Because the restrictions is difficult to reconstruct, it is relatively easy to delete the rewrite, so the programmer can write it first and then change it without satisfaction.

The idea is wrong. Why? Because the Debug process is also time-consuming.

I have also recently perfected a number of programs that require a very clear understanding of the architecture itself. It took me nearly a day to understand the workings of the entire process, and it could take only 5 minutes if there were any comments.

To avoid introducing bugs, I need to understand the possible consequences of any minor adjustments. Without annotations, I had to spend a lot of time understanding the meaning and function of each piece of code. Especially for thousands of lines of code, it's time-consuming to read it first, and to get rid of one of those lines, I have to understand the impact that small adjustments might have on the overall architecture and logic. In the end, I only changed 180 lines of code in more than one weeks, and that's a small change for a thousand-line program.

Debug is just a small part of writing code. These thousands of lines of code a lot I wrote 10 years ago although I still have some remnants of memory, but if there are comments, the process of modifying the code will be more smooth, I can not only in the shortest possible time to read the entire framework, but also to accurately locate the part I want to modify.

Changing other people's code is more difficult, everyone's way of thinking is different, if there is no annotation, I usually spend twice times more time, just to modify some small errors.

So what does my so-called "annotation" mean? Note "refers to the text appended to the code that describes the formal specification. But what's needed is that if we just build a tool room, we don't need a whole set of skyscraper blueprints, and we don't need to annotate every piece of code for small algorithms.

The most recent program I'm going to write is "cottage", not skyscrapers. I will attach a comment for each algorithm I have, some very simple algorithms, I usually only insert one or two comments. I have a very simple rule to help me and others understand my program: annotations should be as effective as possible to help anyone understand and use my code.

Once I know what a line of code is going to do, the process of writing is very simple and straightforward. Some programs need to use unconventional algorithms, and then I write down the main idea of my algorithm to test its feasibility and help me Debug more efficiently.

In addition to those particularly important code, my comments are usually informal. For the past 10 years, I haven't had much time to write accurate and formal notes. But for a very complex system, the importance of annotations is self-evident. Few engineers spend time writing notes when building a complex system. Some schools also teach you how to write notes, but more often than not they teach you how to write code. It takes practice, and if you don't draw a picture of a cottage, it's hard to draw the blueprint of the skyscraper directly.

There is no simple guideline for writing a note, but one thing you should try to avoid is to use code to interpret the code. It's like you can't use one of the two things that people don't understand to explain the other one. The architect can't tell you directly what kind of house he wants to build.

The best way to understand a complex system is to generalize it with simple concepts and abstractions. Some basic concepts of junior maths can be used to help you write notes, such as you can use some sets, equations, and simple logic to explain your code. For some complex algorithms, you can also introduce concepts that are not in mathematics to explain them. In general, it is harder to understand if your comments deviate from some abstract mathematical basic concepts.

Thinking does not guarantee that we make no mistakes, but without thinking, mistakes are unavoidable. Annotations can help us minimize errors, and it also improves the efficiency of our mistakes and saves us time.