×
Community Blog PHP Best Practices: Good Semantic Expressions for Your Code

PHP Best Practices: Good Semantic Expressions for Your Code

In this article, we will discuss the importance of having good semantic expressions in your code for collaborative coding and for troubleshooting unknown code issues.

Do not make your code unintelligible to others, because you might be one of the others who read the unintelligible code after one week. Always supervise yourself by bearing in mind that another developer may take a long time to process bugs if your code snippets have some faults.

In your everyday programming practices, make deliberate efforts to improve your semantic expressions. This will benefit you a lot. Specifically, how can we achieve good semantic expressions?

1

Code samples in this article are only my test code and do not belong to any real projects.

Naming Your Functions and Parameters

Case 1

2

Case 2

With this function name and parameter name alone, who can figure out the actual meaning of this parameter?

3

Case 3

4

Case 4

Assume the following classes are included in our business code.

However, we find the following when querying the database:

5

In this case, it is inconvenient to find corresponding tables according to the business code. Others will also feel confused when taking over our project. This inconvenience maybe caused by three iterative development cycles from three different persons, neither of whom has referred the naming rules used previously.

Additional Remarks

6

Adding Comments to Your Code

After the preceding description about naming, now let's move on to the comment. Is it even necessary to talk about comments? Are you kidding me?

Those questions may come to your mind. However, do you know how to write a comment on an array member object?

Do you know how to write comments on calls on magic methods of a class?

Object Array

7

8

The Use of @method

9

The Use of @deprecated

10

Additional Considerations

Comments and descriptions do match correctly. Method names are updated, while the business and feature comments for the methods are not updated. The @author information entry is also copied during the process of copying others' code and the original code author is ends up taking the blame for the code errors.

For more information about comments, refer to the web page http://manual.phpdoc.org/HTMLframesConverter/default/

Functions and Methods

Case 1

First, I want to make one thing clear: Code with poor readability does not necessarily mean that the software is not good. It is common to see many bad PHP and MySQL code snippets.

The following is a code snippet of an open-source project. The feature is actually excellent. However, this method has too much content. I have listed some shortcomings of the code in the figure.

11

Case 2

Do you still remember this figure?

12

Optimization solution 1Optimization solution 2

$startId and $lastId are repeated parameters.

Case 4

Minimize parameter references

function bad($input1, $input2, &$input3)
{
    //...logic

    $input3 = "xxx";

    return true;
}

Case 5

Ensure the parameter type and the type of return values are clearly described and avoid the use of mixed types. Let's take the following official code for example. It is also necessary to be skeptical about authoritative practices. This is only my opinion.

13

Case 6

14

In this example, the addUser is written in a way that makes it more like a remote API interface rather than a function (method). In the code snippet shown on the right side, we need to make judgement based on is_array every time we use it. This is an unfriendly semantic expression. Exceptions may occur in advanced languages like PHP and Java. We need to make good use of exceptions.

15

Good semantic expressions make it easier to implement efficient iteration in a collaborative team and troubleshoot unknown code issues online. This is the end of this blog. Have you learned something new?

16

0 0 0
Share on

zhoumengkang

3 posts | 0 followers

You may also like

Comments

zhoumengkang

3 posts | 0 followers

Related Products

  • Dedicated Host

    DDH is a solution for security and regulation implementation and flexible resource deployment. It offers dedicated resources in Alibaba Cloud for industries such as government departments, enterprises, and financial institutions.

    Learn More
  • Elasticsearch

    Alibaba Cloud Elasticsearch is based on the open-source Elasticsearch engine and provides commercial X-Pack plug-ins. Designed for scenarios such as search and analytics, Alibaba Cloud Elasticsearch features enterprise-level access control, security monitoring, and automatic updates.

    Learn More
  • Managed Security Service

    Identify vulnerabilities and improve security management of Alibaba Cloud WAF and Anti-DDoS and with a fully managed security service

    Learn More
  • DirectMail

    A simple and efficient email service to help you send transactional notifications and batch email

    Learn More