About code classification

Oh, the code

When I write code, I like to be aware of what I am doing.

For example, code that is written overnight for demos tomorrow morning is very different from code that will become the main API of the system.

In this post I would like to talk about different types of code and give some tips that help me at night before demo, and when designing large APIs.
')

Code "for yourself"

This is a code that solves one problem once in a lifetime. This could be, for example, a solution to a “challenge for wits,” or by calling some complex function to see “how it works,” or a script that gets rid of every third point in the file, or “Hello, world!” In a new language. .

Since the lifetime of such programs is not more than a couple of days, it is very simple to write them: you don’t have to worry about readability, comments, input validation, unit tests, etc.
This code should never appear in a version control system. Moreover, I prefer not to show this code to other developers.

Prototype code

This is the code that should implement the minimum functionality of a new feature. It can be almost anything, anything: a trial integration with another product, a fundamentally new functionality, and a new feature of an existing product. Often, the implementation of the prototype must be completed in a short time.

To write a good prototype in time is quite difficult. I developed the following rules for developing such code: first, the code must be readable. Meaningful names of variables, classes and functions, coding standards, etc. Secondly, comments should be at least near the most complex areas. Thirdly, if deadlines are tight, then you can get by with only the most basic unit tests and hardly care about checking the output. All this can be added when the prototype becomes a full-fledged part of the system.

There is another important rule. If the old code needs to change the old code, the change should have a comment. Although the change may be obvious at the time of writing the prototype, in a few months it will be very difficult to understand what I wanted to do. Especially if the prototype had to throw.

Main code

This is the code of the system itself. What is released, what QA is testing, what users see.

About how to create this code they write books. My favorite is McConnell's Code Complete Book.

I will not dwell on the general rules for creating the main code. However, I would like to highlight four categories of main code.

API

This is the part of the component that the rest will use. I really like it when each member of the development team creates a component and provides the rest of the API to use.

It is clear that all methods and API classes must have the best documentation, the most thorough data checks, the most readable unit tests.
And, of course, the API itself should be easy to use. I recommend the presentation of the Flea How to Design a Good API and Why it Matters .

Integration point

If I develop a component together with a colleague, then integration points are those parts of the code that a colleague must change in order to integrate their changes. The most frequent comment in such places: "//TODO: Your code here" .

Integration points should have good documentation (maybe not as meticulous as an API). Moreover, it should be clear how to integrate its part of the component. Sometimes an example helps.

It seems to me that it is very important to single out integration points into separate classes (or files). Firstly, this code changes quite often, secondly, there are always a lot of errors in it, thirdly, with further development all conflicts (in the sense of the version control system) arise precisely at these points.
Moreover, if your colleague needed to change any part of the component outside the integration point, then most likely something is wrong with the architecture (the component is too closely connected within itself).

Growth point

This is part of the component, which will most likely be updated with new features. For example, this is the code that creates the context menu. As the system grows, the context menu will likely increase. Another example: content delivery systems. Although initially only one can be supported, most likely in the future you will need to add a few more.
It is clear that for such points the factory method and abstract factory are used .

At first glance, these parts of the code differ little from integration points. However, if the integration inside the component is usually carried out once by those two people who wrote the parts, the different people can repeatedly expand the component. Therefore, I try to treat growth points more as an API: meticulous documentation, input checks, plenty of examples.

I specifically highlighted the growth points in a separate category. It is very important to understand early that this piece of code is a growth point. If this moment is missed, then each subsequent addition will add new hacks. If there are more than 2000 lines in a class (or file), then this is most likely a running extension point.
Moreover, it is at these points that dependencies on other components often appear. This is another argument in favor of separating growth points into a separate class (or file).

The rest of the code

And this is all the rest. Many articles have been written about this type of code. I try to write this code so that in half a year I was pleased to read it.

Conclusion

It seems to me that it is very important to be aware of exactly which code you are writing. This speeds up the development process and makes the code better.

What other types of code worth highlighting? Maybe we should add some tips?