Code design
With this topic I want to raise the question of the quality of the code, regardless of the programming language used. In the topic I will give a couple of tips and techniques that are followed in our company. I will not argue that they are true, because everyone has their own taste and preferences. But still, in each circle of developers working together, there are some rules for code design.
Also, it’s important to see your approaches and “favorite style” in the comments.
Most of the tips in the topic are clippings from McConnell's “Perfect Code” (Steve McConnell - “Code Complete”).
Numerous statistical studies show that the average programmer spends much more time reading the code, rather than writing it. Reading the code is harder than writing it. Especially when it comes to someone else's code. But you can seriously facilitate the work of yourself and your colleagues, if your code is high-quality, understandable. “Code quality” is a rather broad term that includes quite a lot of different aspects, among which are the design of class interfaces and methods, the implementation of methods, the correct interaction of classes and methods with each other, conventions on formatting and formatting code, naming classes, methods and variables, adopted in a specific corporate environment.
')
Rule Zero : strictly follow the code style “guidelines” adopted in your corporate environment.
This goal should be fully reflected in its name: get the current user - getCurrentUser () . Blurred, ambiguous and frankly bad method name is most often
the main evidence of its unsuccessful implementation.
Examples of good method names:
Examples of bad method names:
The essence of this advice is simple - any variable must have a clear name by which one can judge
about her purpose. Senseless and non-obvious variables should be avoided. The name of a variable should characterize the problem of the real world, and not its solution in a programming language. The easiest way is to speak the essence of the variable being described by words and name the variable with the corresponding words.
The name of the variable should not be too short to mislead people, but at the same time it should not be too long, as it is ugly in terms of reading the code. The length should be sufficient so as not to have to wrestle with.
The variable names should use the specifiers Count and Index instead of Num. This is logical, since they clearly reflect the purpose of the variable (number and number), but Num looks rather ambiguous and can in some cases be misleading.
This is normal when a small cycle of 1-3 lines has an index called I, j or k. But if the body of the cycle is noticeably larger, then it is better to give the index meaningful names. And it will be easier for you to deal with such code over time (it becomes immediately clear what the loop is doing) and other programmers who will work with your code will also become easier.
When using enumerations it makes sense to prefix. For example, in the case of such variables STATUS_OPENED, STATUS_TO_CONFIRM, STATUS_CONFIRMED, the enumeration comes with the prefix STATUS_.
When naming constants, you should use not the specific numbers, but the abstract entities in question. This is more understandable in terms of code readability and is a good programming style.
You should use variable naming conventions that will be known to the entire team of programmers. The code must be uniform. So each project participant will be much easier to understand it. And this will lead to increased work efficiency. The convention should be obvious and accessible to all. And every developer should stick to it.
When naming a variable, try to give it a not too generalized name. Go towards concretization. It is necessary to clearly understand what it is intended for. Even if this is understandable to you when summarizing, it’s far from a fact that it will be obvious to other developers in your team.
Examples of good variable names:
Examples of bad variable names:
Just as important is the same design of the code blocks, the splitting of long conditions into several lines and the use of indents.
Agree to read this code:
More pleasant than
Link to the book Code Complete.
Thanks for attention.
Also, it’s important to see your approaches and “favorite style” in the comments.
Most of the tips in the topic are clippings from McConnell's “Perfect Code” (Steve McConnell - “Code Complete”).
Numerous statistical studies show that the average programmer spends much more time reading the code, rather than writing it. Reading the code is harder than writing it. Especially when it comes to someone else's code. But you can seriously facilitate the work of yourself and your colleagues, if your code is high-quality, understandable. “Code quality” is a rather broad term that includes quite a lot of different aspects, among which are the design of class interfaces and methods, the implementation of methods, the correct interaction of classes and methods with each other, conventions on formatting and formatting code, naming classes, methods and variables, adopted in a specific corporate environment.
')
Rule Zero : strictly follow the code style “guidelines” adopted in your corporate environment.
Qualitative methods
The method should serve one well-defined goal.
This goal should be fully reflected in its name: get the current user - getCurrentUser () . Blurred, ambiguous and frankly bad method name is most often
the main evidence of its unsuccessful implementation.
Examples of good method names:
Customer :: getFullName () - get the full client name UserMapper :: createAndGetUser (userId) - an exception, in the context of the User-mapper, the side role of the method (to return a newly created user object) is quite obvious.
MonthRevenue.calculate (), MonthRevenue.export () - the non-informative method names themselves are completely sufficient in the context of OOP calls of these methods "to themselves" (in other words, the method is intended to perform an action on the object and its data).
Examples of bad method names:
computeMonthRevenueAndDoExport () - several unrelated targets
processInput (), handleCalculation () - inexpressiveness, blurring the goal
method
- You should use paired antonyms for methods that perform paired (opposite) actions: open / close, show / hide, add / remove, insert / delete.
- The method must be formatted in strict accordance with accepted conventions, "code styles" and so on.
- The method must be documented (both the method interface itself and comments on important and complex areas).
- The method should not change global variables.
- The method should not have too many parameters (no more than 7).
- Parameters should be ordered by degree of importance or the order of their use within the method:
setMonthExchangeRate (month, exchangeRate)
getCustomerMonthRevenue (customerId, month) - Unchangeable parameters should not be passed by reference.
- There should be no unused "abandoned" variables and parameters.
- Do not use input parameters as work variables.
- The method should be protected from bad data that can disrupt its operation.
monthRevenue = fixedValue * 0.6 / inputParam
- The method should not be too large (no more than 100 lines).
Qualitative variables
The variable must fully describe the entity being represented.
The essence of this advice is simple - any variable must have a clear name by which one can judge
about her purpose. Senseless and non-obvious variables should be avoided. The name of a variable should characterize the problem of the real world, and not its solution in a programming language. The easiest way is to speak the essence of the variable being described by words and name the variable with the corresponding words.
Moderate length
The name of the variable should not be too short to mislead people, but at the same time it should not be too long, as it is ugly in terms of reading the code. The length should be sufficient so as not to have to wrestle with.
Qualifiers
The variable names should use the specifiers Count and Index instead of Num. This is logical, since they clearly reflect the purpose of the variable (number and number), but Num looks rather ambiguous and can in some cases be misleading.
Cycle indices
This is normal when a small cycle of 1-3 lines has an index called I, j or k. But if the body of the cycle is noticeably larger, then it is better to give the index meaningful names. And it will be easier for you to deal with such code over time (it becomes immediately clear what the loop is doing) and other programmers who will work with your code will also become easier.
Enum prefixes
When using enumerations it makes sense to prefix. For example, in the case of such variables STATUS_OPENED, STATUS_TO_CONFIRM, STATUS_CONFIRMED, the enumeration comes with the prefix STATUS_.
Constants
When naming constants, you should use not the specific numbers, but the abstract entities in question. This is more understandable in terms of code readability and is a good programming style.
Convention
You should use variable naming conventions that will be known to the entire team of programmers. The code must be uniform. So each project participant will be much easier to understand it. And this will lead to increased work efficiency. The convention should be obvious and accessible to all. And every developer should stick to it.
Less generalization
When naming a variable, try to give it a not too generalized name. Go towards concretization. It is necessary to clearly understand what it is intended for. Even if this is understandable to you when summarizing, it’s far from a fact that it will be obvious to other developers in your team.
Examples of good variable names:
employeesCount, userMonthWorkDaysCount, yearTax, maxComputedSalary
Examples of bad variable names:
x, $ fb, f_ar_type_data, f_obj_result, inputData, returnValue, resultArray, obj1, obj2
- A good rule is to give shorter names to variables with a narrower scope, respectively, longer and more detailed names to variables with a more global (within the method) scope.
- For variable-counters of short cycles, traditional single-character names are allowed - i, j, k, .... If the variable will be used outside the loop, its name should be more expressive and understandable:
teamScoresCount = 0; teamScores = array(); while (teamScoresIterator.nextScore()) { teamScores[teamScoresCount++] = teamScoresIterator.getCurrentScore(); } foreach ($teamScores as $teamScoreIndex => $teamScoreValue) foreach ($aTeamScores as $iTeamScoreIndex => $iTeamScore) { // over 9000 lines of code } - Avoid abbreviations and non-obvious abbreviations. Bad: cl (call stack), gfx (graphics), dpt (department).
- Use only agreed abbreviations: only max or only maximum; only num or only no; months either by the first three letters (Jan, Feb, Mar) or completely.
- Avoid names with similar values ​​(within a specific scope): fileNumber / fileIndex; scoresNumber / scoresCount. Use only one of the options. Write names without spelling errors
- Avoid naming variables with meaningless (meaning only to you) names (snuffi, elizabeth) unless they are entities represented in the program.
- The names of Boolean variables must be in an affirmative form and imply a boolean value: done, error, found, finished. Bad: status, source.
- Minimizing the scope of a variable:
- Have teams using the same variable as possible
closer together - Initialize variables immediately before use.
- Have teams using the same variable as possible
- Use each variable with only one goal.
Initialize variables with a default value.
Just as important is the same design of the code blocks, the splitting of long conditions into several lines and the use of indents.
Agree to read this code:
function() { $a = 1; $b = 2; $c = 3; $sql = ' SELECT * FROM tbl WHERE a = 1'; } More pleasant than
function(){ $a = 1; $b = 2; $c = 3; $sql = 'SELECT * FROM tbl WHERE a = 1'; } Link to the book Code Complete.
Thanks for attention.
Source: https://habr.com/ru/post/145850/
All Articles