Names of methods and functions
Studying all kinds of systems, I discovered that many people have problems with naming methods. This prompted me to write an article.
After I got into the manual for the thousandth time to find out the order of the arguments in the PHP function str_replace , it became clear that the problem is very relevant. After all, the name of the function “str_replace” tells us only what it does, but says nothing about the arguments. What is it fraught with? Okay, you can remember the number and order of the arguments in the built-in library, but in your own design, remembering the arguments is not so simple. Yes, there are development environments that tell us, but they do not work when you hover over the function, so it’s difficult to read such code. But it is important that the code is easy to read and understand without comment. This is a sign of quality code.
As an example of numerous errors, give PHP. I can immediately name a few mistakes:
')
1. The names of some functions do not clearly convey the purpose. For example, basename .
2. The names of the functions are not based on one principle. For example, string functions begin with str_ , but not all (for example, strstr , strpos ). Files have the same problem: filesize vs file_exists .
3. Non-obviousness of arguments and their order in functions. For example, the required string in the str_replace function comes in last place, and in the strpos function - on the first ( str_replace ($ search, $ replace, $ subject [, $ & count]) vs strpos ( $ haystack , $ needle [, $ offset]) ). If the required string, for example, always took the first position, it would be more convenient.
Yes, such is the legacy of C (and not only), but it does not matter: the problem is the problem.
So, we need to invent the names of the methods / functions so that:
1. The name of the function / method clearly conveyed its purpose.
2. Names of functions / methods are compiled according to one principle / standard.
3. The order and the list of arguments in functions / methods were compiled according to the same principle and combined with the name.
4. Methods remained methods.
I will explain the fourth point. Often I meet lines of the form object.Pi (): this method has nothing to do with an object. It is rather a function (or constant).
1. We need to replace the substring in the string. The most obvious option would be: string.replace (from, to). It is a pity that in PHP it is not feasible.
2. Hint at the arguments and meaning: groups.getByName (name). Nothing extra. Do not write getGroupByName, because the context is clear thanks to groups. Similarly, other methods: groups.remove (group) or group.delete () . Aha And here is an interesting moment :) If we remove from the collection, then the collection.remove (element) . And if the element itself deletes itself, then the element.delete () . And this is important: our code must be valid in terms of English.
3. Antonyms in function / method names. Yes, you should always use the correct antonyms when naming. Add and remove items in the collection: add / remove. Create and delete: create / delete objects. We begin and end the process: begin / end, start / finish (but not begin / end and start / end).
4. Boolean return values. Yes, yes, yes, and this should be hinted to make the code easy to read. Words like: has, is, was, have at the beginning of the method name hint that this method returns a boolean value. Example: object.hasData () . Thank you kroz for the reminder.
5. Hint at the order of the arguments in the method: cars.getByMonthAndYear (month, year) .
6. Formation of the name. The name of the method is a peculiar sentence that necessarily consists of a predicate ( input.focus () ), but may contain additions ( element.appendChild () ), definitions ( window.slowlyShow () ) and their combinations ( todo.getNewTask () ) . But the rule is often broken. For example, user.next (). Yeah ... were similar situations? This problem is inherent in programming languages in which there are no properties (property). Yes, you have to put up with such names. Whether this is bad or good is up to you.
I hope this article was helpful to you. Want more? Then go to the bookstore and buy Steve McConnell's The Perfect Code.
What prompted me to write an article?
After I got into the manual for the thousandth time to find out the order of the arguments in the PHP function str_replace , it became clear that the problem is very relevant. After all, the name of the function “str_replace” tells us only what it does, but says nothing about the arguments. What is it fraught with? Okay, you can remember the number and order of the arguments in the built-in library, but in your own design, remembering the arguments is not so simple. Yes, there are development environments that tell us, but they do not work when you hover over the function, so it’s difficult to read such code. But it is important that the code is easy to read and understand without comment. This is a sign of quality code.
As an example of numerous errors, give PHP. I can immediately name a few mistakes:
')
1. The names of some functions do not clearly convey the purpose. For example, basename .
2. The names of the functions are not based on one principle. For example, string functions begin with str_ , but not all (for example, strstr , strpos ). Files have the same problem: filesize vs file_exists .
3. Non-obviousness of arguments and their order in functions. For example, the required string in the str_replace function comes in last place, and in the strpos function - on the first ( str_replace ($ search, $ replace, $ subject [, $ & count]) vs strpos ( $ haystack , $ needle [, $ offset]) ). If the required string, for example, always took the first position, it would be more convenient.
Yes, such is the legacy of C (and not only), but it does not matter: the problem is the problem.
Aha
So, we need to invent the names of the methods / functions so that:
1. The name of the function / method clearly conveyed its purpose.
2. Names of functions / methods are compiled according to one principle / standard.
3. The order and the list of arguments in functions / methods were compiled according to the same principle and combined with the name.
4. Methods remained methods.
I will explain the fourth point. Often I meet lines of the form object.Pi (): this method has nothing to do with an object. It is rather a function (or constant).
Examples and not only
1. We need to replace the substring in the string. The most obvious option would be: string.replace (from, to). It is a pity that in PHP it is not feasible.
2. Hint at the arguments and meaning: groups.getByName (name). Nothing extra. Do not write getGroupByName, because the context is clear thanks to groups. Similarly, other methods: groups.remove (group) or group.delete () . Aha And here is an interesting moment :) If we remove from the collection, then the collection.remove (element) . And if the element itself deletes itself, then the element.delete () . And this is important: our code must be valid in terms of English.
3. Antonyms in function / method names. Yes, you should always use the correct antonyms when naming. Add and remove items in the collection: add / remove. Create and delete: create / delete objects. We begin and end the process: begin / end, start / finish (but not begin / end and start / end).
4. Boolean return values. Yes, yes, yes, and this should be hinted to make the code easy to read. Words like: has, is, was, have at the beginning of the method name hint that this method returns a boolean value. Example: object.hasData () . Thank you kroz for the reminder.
5. Hint at the order of the arguments in the method: cars.getByMonthAndYear (month, year) .
6. Formation of the name. The name of the method is a peculiar sentence that necessarily consists of a predicate ( input.focus () ), but may contain additions ( element.appendChild () ), definitions ( window.slowlyShow () ) and their combinations ( todo.getNewTask () ) . But the rule is often broken. For example, user.next (). Yeah ... were similar situations? This problem is inherent in programming languages in which there are no properties (property). Yes, you have to put up with such names. Whether this is bad or good is up to you.
Total
I hope this article was helpful to you. Want more? Then go to the bookstore and buy Steve McConnell's The Perfect Code.
Source: https://habr.com/ru/post/44748/
All Articles