Do I need a development standard?
Free translation of the article “ Should we use a coding standard? "From the blog" Virtuous Code "Avdi Grimm. The opinion of the author of the original article may not coincide with the opinion of the publisher.
Translator's note: I personally agree with the author.
Avdi, should we use a development standard?
')
Yes.
What standard should we use?
I do not think that there is any one "correct" standard. Each project should develop its own standard based on its needs and preferences of developers.
I think the variety of styles in the community is good. This is good even for a large organization.
When I worked in such an organization, we had a couple of recommended standards for any language we use. But the final choice of standard for each new project remained on the conscience of the tmlid.
I think that the choice of standard for each specific project is good detail. Thus, each individual repository and each team can have a separate standard.
How do we choose a development standard?
Many communities of programming languages have already developed common standards. For example, if you are writing C code, you can choose the GNU development standard . Or if you are developing in Ruby, you can use the community standard supported by Bozhidar Batsov: Bozhidar Batsov's community-influenced standard .
These standards are the fruit of community thoughts and debates. Since the agreements included in these standards are based on a majority decision, this is a good starting point.
But some decisions in these standards are stupid and wrong!
True. That's why I say community standards are a good starting point. When your team has clear objections to certain agreements in the standards - it's time to modify the standard to fit your needs.
Our team is divided in half in choosing a particular path! How can I convince the other half?
Let's be honest: it is very unlikely that the team is really divided in half. Usually there are one or two people on the one hand and about the same on the other, the rest of the team does not choose either side.
OK, so how can I convince these people on the other side of the barricades?
The confidence of the other side can be shaken by well-founded, real-life examples of the fact that your version more elegantly reveals the essence of the code, is more concisely written, or shows better dangerous places.
It's not like that, just my style is more beautiful. In any case, this is a more idiomatic approach.
After many years of acquaintance with different development standards, I can say that acquaintance with this standard is most affected by the attitude to the standard. I do not even remember how many times I came to the project with a standard that I just hated, but after six weeks of work I stopped worrying about it. Sometimes I even used it as a new standard for my own projects.
For example, when I started developing in C ++, I aligned curly braces so that you can look above and immediately see the opening bracket in the same column:
Later, I met with GNU / GNOME-style code, where the opening bracket stands on the line with the method declaration. Argh!
I shrugged and continued. The GNU style option even seemed preferable to me.
I encountered many examples of code like “A vs. B”, where option B was objectively more beautiful than option A. Most of the time it was difficult for me to see the difference, which the author considered obvious.
In Ruby, the popularized Rails choice agreement between curly brackets and do ... end, based on the number of lines of code inside a block, is a bit silly. I was told that one of the reasons for this agreement is that the do ... end on one line objectively looks awful:
Personally, I see nothing wrong with this line. Objective aesthetic judgments are bad as rules.
It is worth remembering that the “standard” syntax of the language is usually a bit strange at the beginning. For example, in each C-based language we denote a “message” or “attribute” like this:
Since these are words in English, let's look at it from the point of view of the English language.
A dot usually indicates the end of a sentence, or a separator between the integer and fractional parts of a number. Here it stands on the place where we usually put a comma:
Or a colon:
In the meantime, words are separated from each other by a symbol that beginners do not know at all . I don’t even want to think about quotes.
Okay, well, the style is subjective. But some things really make the code easier, or errors are more noticeable!
Yes, I think so.
And my team leader makes the wrong choice !!
It is possible that you really have good, holistic, code-quality arguments for a particular style. And the question of choosing a standard can really dissolve you and your team on opposite sides of the barricades.
There is one important question that you need to ask yourself, standing up for choosing a particular style of code. It is so important that I write it in a separate line.
Let's see: you are completely right about the choice of style or development practice. Your opponents are wrong and stupid.
But ask yourself whether your correctness will save enough to compensate:
Some design standards are worth it all. But I recommend to think well before rushing into battle.
Standards of development protect against bad habits, but what is their main advantage?
Development standards give programmers, especially inexperienced, some protection against bad habits, but I do not consider this a major advantage. For me, the main gain from standards is consistency.
Compare two blocks of Ruby code:
Is it obvious at first glance that both units are doing the same thing? More importantly: is it obvious that, despite the similar functionality, the blocks have a small but important difference?
The real value of a development standard is that it makes similar things look alike, while different things are different. Such a sequence helps the team to quickly understand the essence of the written code. In turn, this means that they can work at a higher level of abstraction most of the time.
How to understand this for Legacy code? Should we update every file in the project for a new standard?
In a word - no. I see no use in spending hours updating each file in the project line by line according to the new development standard. It is not worth the cost of time and effort, and can bring new bugs in Legacy code.
What if I make a change to the Legacy code? Do I have to update the entire file, since I took it?
My answer differs from the conventional wisdom and sometimes surprises people.
The answer is no. Updating the legacy code style will take time, create a big diff and increase the chance of random regression.
Does this mean that I should use the new style only in new or modified parts of the code?
Let's specify a question. Imagine that this is a piece of legacy code:
Suppose your task is to add the word “they” to the list. And according to the new development standard, all strings should be framed with double quotes.
Do I need to update the entire list in the process of adding a new word?
Or apply a new standard only for the added string?
As I said before, for me the value of the standard is the preservation of the sequence. Consistency is important at the project level, but it is also important at the file level. Therefore, I do not think that it is necessary to follow the new standard when you update a file written according to the old standard. On the contrary, if the file already has a consistent style of design, you should try to sustain it.
This means that if the words in the list are framed with single quotes, you must add a new word in single quotes.
If you frequently update a file with legacy code, then it seems to me a good idea to schedule an update of this particular file according to new standards. But I do not think that it is worthwhile to proactively update little-used files. And I do not support locally inconsistent changes just to stay within the standard.
___
What do you think about design standards? What standards do you apply? Tell me about it.
Translator's note: I personally agree with the author.
Avdi, should we use a development standard?
')
Yes.
What standard should we use?
I do not think that there is any one "correct" standard. Each project should develop its own standard based on its needs and preferences of developers.
I think the variety of styles in the community is good. This is good even for a large organization.
When I worked in such an organization, we had a couple of recommended standards for any language we use. But the final choice of standard for each new project remained on the conscience of the tmlid.
I think that the choice of standard for each specific project is good detail. Thus, each individual repository and each team can have a separate standard.
How do we choose a development standard?
Many communities of programming languages have already developed common standards. For example, if you are writing C code, you can choose the GNU development standard . Or if you are developing in Ruby, you can use the community standard supported by Bozhidar Batsov: Bozhidar Batsov's community-influenced standard .
These standards are the fruit of community thoughts and debates. Since the agreements included in these standards are based on a majority decision, this is a good starting point.
But some decisions in these standards are stupid and wrong!
True. That's why I say community standards are a good starting point. When your team has clear objections to certain agreements in the standards - it's time to modify the standard to fit your needs.
Our team is divided in half in choosing a particular path! How can I convince the other half?
Let's be honest: it is very unlikely that the team is really divided in half. Usually there are one or two people on the one hand and about the same on the other, the rest of the team does not choose either side.
OK, so how can I convince these people on the other side of the barricades?
The confidence of the other side can be shaken by well-founded, real-life examples of the fact that your version more elegantly reveals the essence of the code, is more concisely written, or shows better dangerous places.
It's not like that, just my style is more beautiful. In any case, this is a more idiomatic approach.
After many years of acquaintance with different development standards, I can say that acquaintance with this standard is most affected by the attitude to the standard. I do not even remember how many times I came to the project with a standard that I just hated, but after six weeks of work I stopped worrying about it. Sometimes I even used it as a new standard for my own projects.
For example, when I started developing in C ++, I aligned curly braces so that you can look above and immediately see the opening bracket in the same column:
int main(int argc, char** argv) { std::cout << "Hello, world!"; } Later, I met with GNU / GNOME-style code, where the opening bracket stands on the line with the method declaration. Argh!
int main(int argc, char** argv) { std::cout << "Hello, world!"; }
I shrugged and continued. The GNU style option even seemed preferable to me.
I encountered many examples of code like “A vs. B”, where option B was objectively more beautiful than option A. Most of the time it was difficult for me to see the difference, which the author considered obvious.
In Ruby, the popularized Rails choice agreement between curly brackets and do ... end, based on the number of lines of code inside a block, is a bit silly. I was told that one of the reasons for this agreement is that the do ... end on one line objectively looks awful:
h.fetch(:some_key) do raise ":some_key is required" end
Personally, I see nothing wrong with this line. Objective aesthetic judgments are bad as rules.
It is worth remembering that the “standard” syntax of the language is usually a bit strange at the beginning. For example, in each C-based language we denote a “message” or “attribute” like this:
farm_boy.fetch_me_that_pitcher()
Since these are words in English, let's look at it from the point of view of the English language.
A dot usually indicates the end of a sentence, or a separator between the integer and fractional parts of a number. Here it stands on the place where we usually put a comma:
"Farm boy, fetch me that pitcher"
Or a colon:
"Farm boy: Fetch me that pitcher!"
In the meantime, words are separated from each other by a symbol that beginners do not know at all . I don’t even want to think about quotes.
Okay, well, the style is subjective. But some things really make the code easier, or errors are more noticeable!
Yes, I think so.
And my team leader makes the wrong choice !!
It is possible that you really have good, holistic, code-quality arguments for a particular style. And the question of choosing a standard can really dissolve you and your team on opposite sides of the barricades.
There is one important question that you need to ask yourself, standing up for choosing a particular style of code. It is so important that I write it in a separate line.
How expensive will your project be?
Let's see: you are completely right about the choice of style or development practice. Your opponents are wrong and stupid.
But ask yourself whether your correctness will save enough to compensate:
- Spent hours of the whole team on meetings regarding the style, which do not end in any sensible?
- Losing a good relationship as a result of head-on collisions at these meetings?
- The price of huge chains in the mail with discussions of the pros and cons of different standards?
- Anger and anger of your team, when they will be forced to follow a style that they do not like, but which they eventually imposed on them?
Some design standards are worth it all. But I recommend to think well before rushing into battle.
Standards of development protect against bad habits, but what is their main advantage?
Development standards give programmers, especially inexperienced, some protection against bad habits, but I do not consider this a major advantage. For me, the main gain from standards is consistency.
Compare two blocks of Ruby code:
# Block #1 output = [] while word = input.shift unless STOP_WORDS.include?(word.downcase) output << word end end
# Block #2 output = input.map(&:downcase) - STOP_WORDS
Is it obvious at first glance that both units are doing the same thing? More importantly: is it obvious that, despite the similar functionality, the blocks have a small but important difference?
The real value of a development standard is that it makes similar things look alike, while different things are different. Such a sequence helps the team to quickly understand the essence of the written code. In turn, this means that they can work at a higher level of abstraction most of the time.
How to understand this for Legacy code? Should we update every file in the project for a new standard?
In a word - no. I see no use in spending hours updating each file in the project line by line according to the new development standard. It is not worth the cost of time and effort, and can bring new bugs in Legacy code.
What if I make a change to the Legacy code? Do I have to update the entire file, since I took it?
My answer differs from the conventional wisdom and sometimes surprises people.
The answer is no. Updating the legacy code style will take time, create a big diff and increase the chance of random regression.
Does this mean that I should use the new style only in new or modified parts of the code?
Let's specify a question. Imagine that this is a piece of legacy code:
STOP_WORDS = [ 'i', 'we', 'if', 'and', 'the' ]
Suppose your task is to add the word “they” to the list. And according to the new development standard, all strings should be framed with double quotes.
Do I need to update the entire list in the process of adding a new word?
STOP_WORDS = [ "i", "we", "if", "and", "the", "they" ]
Or apply a new standard only for the added string?
STOP_WORDS = [ 'i', 'we', 'if', 'and', 'the', "they" ]
As I said before, for me the value of the standard is the preservation of the sequence. Consistency is important at the project level, but it is also important at the file level. Therefore, I do not think that it is necessary to follow the new standard when you update a file written according to the old standard. On the contrary, if the file already has a consistent style of design, you should try to sustain it.
This means that if the words in the list are framed with single quotes, you must add a new word in single quotes.
STOP_WORDS = [ 'i', 'we', 'if', 'and', 'the', 'they' ]
If you frequently update a file with legacy code, then it seems to me a good idea to schedule an update of this particular file according to new standards. But I do not think that it is worthwhile to proactively update little-used files. And I do not support locally inconsistent changes just to stay within the standard.
___
What do you think about design standards? What standards do you apply? Tell me about it.
Source: https://habr.com/ru/post/283080/
All Articles