Why I comment on Ruby / Rails application code again
Hello, I am a Ruby / Rails software developer and I am commenting on my (and more recently someone else's) code. A voice from the audience would probably shout out "Hello, developer!"
Many years ago, it seemed obvious to me the well-established opinion of professionals and development gurus, which usually expresses something like this: “If the code requires a comment, this is bad code, it needs to be rewritten / refactored / simplified / reduced”. Those. bring it to the form, comments and explanations are not required. In general, this approach is quite versatile and works in many cases. Many of my familiar web developers never comment on their code and consider this to be quite normal even if they work in a team. This is probably due to the myth of the simplicity of Ruby, such simplicity that makes the code understandable even to an outsider. However, my personal experience and some episodes of team development of web applications convinced me that there are situations and reasons for devoting more time and attention to comments and documenting code than the developer usually devotes.
Immediately I’ll warn you that there are probably many articles and posts on the Internet that present some point of view on the art of writing code, on the rules and recommendations for each specific programming language. Of course, I cannot know all of them, so there will be no excursion into the history of the issue. There will be only my personal story about my personal experience.
The main thesis of my short story will be: "Only the author can judge the complexity of the code."
')
So, first of all, you need to clarify when exactly the rule “Instead of commenting, change the code so that commenting becomes redundant” will work. It works only in a few cases:
And that's it! In these cases, indeed, it is better to alter such code. To remake, make sure that the code has become shorter, clearer, more understandable for colleagues and ... finally write comments! And now I have reached the place where I will explain my ideas.
Explanation for Idea No. 1: “Only the author can adequately judge the complexity of the code”.
Imagine a team of programmers, consisting, for example, of 5 people. A manager and a couple of designers work with them. The team of programmers consists of one professional and 4 ordinary level programmers. Nobody comments on the code. Perhaps there is someone written a brief instruction on the deployment of the project. Documentation team does not lead, because the customer changes decisions and priorities and does not really want to pay for the time spent on drawing up documentation in the development process. Approximately in this way many mid-level web development studios work.
What will happen if one or two programmers leave the team, to another project, to another studio, or just to leave? Probably, in their place will be taken one and two other developers, who will be given code, will give tasks and ... and that's it. Previously, the HR manager will ask them if they know how to “understand someone else’s code” and “work in a team”, and they, of course, will answer that they can. And the new arrivals will be face to face with the code and colleagues, who may be happy to answer the questions “why is it like this ...” or “why is it there ...”, but it distracts from work. Therefore, the developer is forced to "break with the project." The amount of working time spent on “executing” another's code with the brain in order to pass through it and understand what it is doing is terrifying. Let me explain by example.
Imagine a function like this:
From the point of view of the rule about the simplicity of the code, here is just paradise. There is nothing to comment on, one line, absolutely no difficulties. However, let us imagine that params is not formed by a simple form on the page, but using Javascript code in Backbone.js, that lists are not lists, but the name and model that remains from the last command is now called Things everywhere that the before_save of this model contains a function that takes some fields and creates a pending task that parses, according to the data of these fields, some URLs (possibly, without HTTP error-control error), in order to save the received answers in another table. And sometimes it causes an exception and sends messages about them ... somewhere ... to the error collection site, where the programmer will be given access as soon as he reminds himself. But a completely different controller (API, for example) will give the values ​​of these fields to Backbone's View with ajax. By the way, you can still clarify that this function should render the template, first passing it through the RABL parser, forming JSON there, completely different from the original contents of the list, which is Things. Well, for the complete set, we’ll specify that it should work on hosting with any restrictions, for example, without access to cron. And as a DBMS, NoSQL is used.
The example given is not a fiction, not a special complication. In real projects, there are more steps in performing some function of the application. But always only the author of the code can know whether its code is complex or not. The problem is that a person who needs to implement new functionality in this application will inevitably have to use his brain instead of the interpreter to “execute” almost all of the existing code base. Either he will do it BEFORE writing the code, which he spends the time that the manager will have to somehow justify in the reports, or he will do it in the process of writing the code, which is the worst option. Why? And because the results of such work will be extremely poor quality and the author who has returned from vacation will still redo everything. And you pay a newbie for what he understood with the project, but in the end still did not bring any benefit.
There is another common problem.
In the N project, the M functionality is usually implemented using XYZ. Without knowing the code completely or not reading the project documentation describing the structure and the XZY used, the developer cannot know whether X, Y or Z is already being used or not. And if not, why not? There is no programmer who can immediately start working and create a new project in an unfamiliar to him, this is the myth of the "coolness of the developer." The best that this situation can lead to - the developer will do his task as best he can, give it to code review and get the code back with the comment “Why did it, because we have to use [a list of some technologies]” or “ Why did you do this? After all, it was possible this way: [description of entities whose existence cannot be ascertained independently (for example, the presence of triggers or functions in the database on a production server] ”
So what I propose is already long overdue to ask the reader. First of all, do a few simple things with the code you are working on:
For the last point, I’ll give an example: if your project is incompatible, for example, with MySQL, and the developer spent half a day trying to deploy the project on this DBMS, do not even think to tell him "We do not support MySQL!". In response, you will hear at best, “Why did I not know about it?”. And if you say the phrase “Why didn't you ask?” To this guy, you can be sure. that in your project there are already big problems with documentation and this is already causing you damage. After all, none of us knows the exact list of all that he does not know!
Thank you for your attention and let your code be always clear, simple and documented.
Many years ago, it seemed obvious to me the well-established opinion of professionals and development gurus, which usually expresses something like this: “If the code requires a comment, this is bad code, it needs to be rewritten / refactored / simplified / reduced”. Those. bring it to the form, comments and explanations are not required. In general, this approach is quite versatile and works in many cases. Many of my familiar web developers never comment on their code and consider this to be quite normal even if they work in a team. This is probably due to the myth of the simplicity of Ruby, such simplicity that makes the code understandable even to an outsider. However, my personal experience and some episodes of team development of web applications convinced me that there are situations and reasons for devoting more time and attention to comments and documenting code than the developer usually devotes.
Immediately I’ll warn you that there are probably many articles and posts on the Internet that present some point of view on the art of writing code, on the rules and recommendations for each specific programming language. Of course, I cannot know all of them, so there will be no excursion into the history of the issue. There will be only my personal story about my personal experience.
The main thesis of my short story will be: "Only the author can judge the complexity of the code."
')
So, first of all, you need to clarify when exactly the rule “Instead of commenting, change the code so that commenting becomes redundant” will work. It works only in a few cases:
- When code is written unqualified: too long (perhaps the developer doesn’t know the standard library badly and wrote a lot of extra code himself) or too difficult (perl-style, single-line chains of functions longer than 5 functions in a row)
- When code includes methods that are rarely used or uncharacteristic for a given YP
And that's it! In these cases, indeed, it is better to alter such code. To remake, make sure that the code has become shorter, clearer, more understandable for colleagues and ... finally write comments! And now I have reached the place where I will explain my ideas.
Explanation for Idea No. 1: “Only the author can adequately judge the complexity of the code”.
Imagine a team of programmers, consisting, for example, of 5 people. A manager and a couple of designers work with them. The team of programmers consists of one professional and 4 ordinary level programmers. Nobody comments on the code. Perhaps there is someone written a brief instruction on the deployment of the project. Documentation team does not lead, because the customer changes decisions and priorities and does not really want to pay for the time spent on drawing up documentation in the development process. Approximately in this way many mid-level web development studios work.
What will happen if one or two programmers leave the team, to another project, to another studio, or just to leave? Probably, in their place will be taken one and two other developers, who will be given code, will give tasks and ... and that's it. Previously, the HR manager will ask them if they know how to “understand someone else’s code” and “work in a team”, and they, of course, will answer that they can. And the new arrivals will be face to face with the code and colleagues, who may be happy to answer the questions “why is it like this ...” or “why is it there ...”, but it distracts from work. Therefore, the developer is forced to "break with the project." The amount of working time spent on “executing” another's code with the brain in order to pass through it and understand what it is doing is terrifying. Let me explain by example.
Imagine a function like this:
def update
list = current_user.lists.update (params [: id], params [: list])
end
From the point of view of the rule about the simplicity of the code, here is just paradise. There is nothing to comment on, one line, absolutely no difficulties. However, let us imagine that params is not formed by a simple form on the page, but using Javascript code in Backbone.js, that lists are not lists, but the name and model that remains from the last command is now called Things everywhere that the before_save of this model contains a function that takes some fields and creates a pending task that parses, according to the data of these fields, some URLs (possibly, without HTTP error-control error), in order to save the received answers in another table. And sometimes it causes an exception and sends messages about them ... somewhere ... to the error collection site, where the programmer will be given access as soon as he reminds himself. But a completely different controller (API, for example) will give the values ​​of these fields to Backbone's View with ajax. By the way, you can still clarify that this function should render the template, first passing it through the RABL parser, forming JSON there, completely different from the original contents of the list, which is Things. Well, for the complete set, we’ll specify that it should work on hosting with any restrictions, for example, without access to cron. And as a DBMS, NoSQL is used.
The example given is not a fiction, not a special complication. In real projects, there are more steps in performing some function of the application. But always only the author of the code can know whether its code is complex or not. The problem is that a person who needs to implement new functionality in this application will inevitably have to use his brain instead of the interpreter to “execute” almost all of the existing code base. Either he will do it BEFORE writing the code, which he spends the time that the manager will have to somehow justify in the reports, or he will do it in the process of writing the code, which is the worst option. Why? And because the results of such work will be extremely poor quality and the author who has returned from vacation will still redo everything. And you pay a newbie for what he understood with the project, but in the end still did not bring any benefit.
There is another common problem.
In the N project, the M functionality is usually implemented using XYZ. Without knowing the code completely or not reading the project documentation describing the structure and the XZY used, the developer cannot know whether X, Y or Z is already being used or not. And if not, why not? There is no programmer who can immediately start working and create a new project in an unfamiliar to him, this is the myth of the "coolness of the developer." The best that this situation can lead to - the developer will do his task as best he can, give it to code review and get the code back with the comment “Why did it, because we have to use [a list of some technologies]” or “ Why did you do this? After all, it was possible this way: [description of entities whose existence cannot be ascertained independently (for example, the presence of triggers or functions in the database on a production server] ”
So what I propose is already long overdue to ask the reader. First of all, do a few simple things with the code you are working on:
- Describe how this code works. Be sure, though briefly, at the beginning of each file containing a class, describe what it implements. Before class methods, briefly describe what the method receives and what it should create at the end of its work, briefly describe the chain along which the data will pass. Also in the module files. Comment on the automatically calculated values ​​and assignments of the fields created by the migrations. In the case of a long chain of function calls (longer than three) - describe the chain, which causes that, at least just a sequence.
- Keep a TODO block in each file in the same place, even though immediately after the declaration of a class or module.
- Keep in each file the IN_WORK block (name it as you please), in which write about which places are currently undergoing alteration / refactoring / are outdated and instead you need to use BLABLA from the XYZ class.
- Be sure to describe all the facts, the presence of which can not be derived from the available documentation!
For the last point, I’ll give an example: if your project is incompatible, for example, with MySQL, and the developer spent half a day trying to deploy the project on this DBMS, do not even think to tell him "We do not support MySQL!". In response, you will hear at best, “Why did I not know about it?”. And if you say the phrase “Why didn't you ask?” To this guy, you can be sure. that in your project there are already big problems with documentation and this is already causing you damage. After all, none of us knows the exact list of all that he does not know!
Thank you for your attention and let your code be always clear, simple and documented.
Source: https://habr.com/ru/post/184420/
All Articles