DEV Community: Mehrad Sadeghi

Clean Code Made Simple - Part 3

Mehrad Sadeghi — Mon, 15 Aug 2022 17:28:54 +0000

Further to my last posts Part 1 and Part 2 of Clean Code Made Simple,
in this post I'm going to continue introducing techniques from Robert C. Martin’s Clean Code book.

#11 Law of Demeter

As wikipedia says:

The Law of Demeter (LoD) or principle of least knowledge is a design guideline for developing software, particularly object-oriented programs. can be succinctly summarized in each of the following ways:

Each unit should have only limited knowledge about other units: only units "closely" related to the current unit.

Each unit should only talk to its friends; don't talk to strangers.

Only talk to your immediate friends.

Now that we have a basic understanding of Demeter's law, in order to prevent breaking it, which one of the following structures do you think is better?

$ctx->getAbsolutePathOfScratchDirectoryOption();

$ctx->getScratchDirectoryOption().getAbsolutePath()

well non is good. If ctx is an object, we should be telling it to do something; we should not be asking it about its internals.

Consider far from code about (in that module) we needed the outputDir like below:

$outFile = $outputDir + "/" + $className->replace('.', '/') + ".class";
$fout = new FileOutputStream($outFile);
$bos = new BufferedOutputStream($fout);

So, what if we told the ctx object to do this:

$bos = $ctx->createScratchFileStream($classFileName);

That seems like a reasonable thing for an object to do! This allows ctx to hide its internals and prevents the current function from having to violate the Law of Demeter by navigating through objects it shouldn’t know about.

#12 Standard Pattern Names

By using the standard pattern names, such as COMMAND or VISITOR, in the names of the classes that implement those patterns, you can succinctly describe your design to other developers.

#13 Doing One Thing

How do you think we can figure out a function is doing more than “one thing”?

The answer is that if you can extract another function from it with a name that is not merely a restatement of its implementation, Then you would know it's doing more than one thing.

To do so, we need to make sure that the statements within our function are all at the same level of abstraction. for example
getHtml() is at a very high level of abstraction,
$pagePathName = PathParser::render($pagePath); is at intermediate abstraction,
and something like ->append("\n") is at low level of abstraction

#14 Base Class and Derivatives

The most common reason for partitioning concepts into base and derivative classes is so that the higher level base class concepts can be independent of the lower level derivative class concepts. Therefore, when we see base classes mentioning the names of their derivatives, we suspect a problem. In general, base classes should know nothing about their derivatives.

There are exceptions to this rule, of course. Sometimes the number of derivatives is strictly fixed, and the base class has code that selects between the derivatives. We see this a lot in finite state machine implementations. However, in that case the derivatives and base class are strongly coupled and always deploy together. In the general case we want to be able to deploy derivatives and bases separately.

#15 Naming

Methods should have verb or verb phrase names like postPayment, deletePage, or save.
Accessors, mutators, and predicates should be named for their value and prefixed with get,
set, and is.

$name = employee->getName();
$customer->setName("mike");
if ($paycheck->isPosted())...

Okay. This is it for this part. You can join my Telegram channel to get notified of the latest posts. Also, you can follow me on Twitter and LinkedIn.

Clean Code Made Simple - Part 2

Mehrad Sadeghi — Thu, 11 Aug 2022 16:49:00 +0000

Further to my last post Clean Code Made Simple - Part 1, in this post I'm going to continue introducing techniques from Robert C. Martin’s Clean Code book.

#6 Hiding Data

Which one of below code snippets do you think is better designed?

interface Vehicle {
    public function getFuelTankCapacityInGallons();
    public function getGallonsOfGasoline();
}

interface Vehicle {
    public function getPercentFuelRemaining();
}

In both of the above cases the second option is preferable. We do not want to expose the details of our data as much as possible. Rather we want to express our data in abstract terms. Serious thought needs to be put into the best way to represent the data that an object contains. The worst option is to blithely add getters and setters.

So in any situation where it's suitable to hide the data of an object, You may do it.

#7 Simple Design Rules

Kent Beck introduced these 4 rules as basic criteria to design programs better:

Runs all the tests
Contains no duplication
Expresses the intent of the programmer
Minimizes the number of classes and methods

In an effort to make our classes and methods small, we might create too many tiny classes and methods. we should also keep our function and class counts low. this is the forth rule of simple design rules by kent which is more important than other ones.

#8 Intention Revealing Functions

how do you think this code snippet can get better ?

public function getFlaggedCells() {

    $flaggedCells = new List();

    foreach ($cells as $cell) {
        if ($cell[STATUS_VALUE] == 1) {
            $flaggedCells->add($cell);
        }
    }

    return $flaggedCells;
}

We can write an intention-revealing function (call it isFlagged) to hide the magic numbers. It results in a new version of the function:

public function getFlaggedCells() {

    $flaggedCells = new List();

    foreach ($cells as $cell) {
        if ($cell->isFlagged())
            $flaggedCells->add($cell);

    return $flaggedCells;
}

#9 Writing Tests Leads to Better Designs

Systems that aren’t testable aren’t verifiable. Arguably, a system that cannot be verified should never be deployed. Fortunately, making our systems testable pushes us toward a design where our classes are small and single purpose. Writing tests leads to better designs.

#10 Separation of Concerns

What would you recommend the direction of arrows should be, to separate construction from use ?

Main             Application



Builder

Directions should be as follow:

            run
  Main  --------->  Application
   |
   | build and construct
  \|/
Builder

It simply means that the construction of our application should be separate from using it. These two steps are fundamentally separate and decoupling them gives us a better design and structure.

Okay. This is it for this part. You can join my Telegram channel to get notified of the latest posts. Also, you can follow me on Twitter and LinkedIn.

Clean Code Made Simple - Part 1

Mehrad Sadeghi — Sun, 07 Aug 2022 08:13:00 +0000

I’ve read Robert C. Martin’s Clean Code book a couple of years ago. It’s a great book, Especially for those who are in the junior years of their career. It helps you become a more mature software developer/engineer and write quality code more often.

I aggregated the tips, tricks, and practices I’ve learned from this book and will publish them in multiple parts.

Note that there are quotes and code examples that I’ve used from the original book in this series.

So without further ado, Let’s start.

#1 Short Functions Are Better

What uncle bob says about a function’s length is that the smaller a function is, The better.
He suggests that the block of code inside an if statement, else statement, and while statement should be just one line. Also, the indent level of a function should not be more than one or two.

It’s a good practice if you could do it. It’s not always possible to follow this rule strictly, But try to do it as much as possible.

#2 Introduce Instance Variables When Possible

Passing instance variables instead of primitive parameters into a function is a good idea when it’s proper. But when it’s proper?

Consider a large function with many variables declared within it. Let’s say you want to extract one small part of that function into a separate function. However, the code you want to extract uses four of the variables declared in the function.

This is a situation where passing an instance variable may be a good idea.

class Sample 
{ 
  public function __construct() 
  {

  }

  public function render() 
  {
   // doing some logic
   $this->getHtml($var1, $var2, $var3, $var4);
  }

  private function getHtml($var1, $var2, $var3, $var4) 
  {
   // doing some logic with vars
  }
}

Will become:

class Sample 
{
  private $var;

  public function __construct(VarThing $var) 
  {
   $this->var = $var;  
  }

  public function render() 
  {
   // doing some logic
   $this->getHtml();
  }

  private function getHtml() 
  {
   // $this->var is accessible here
  }
}

#3 The BUILD-OPERATE-CHECK Pattern

You’ve probably heard of Arrange-Act-Assert or AAA pattern before, Which is similar to the Build-Operate-Check pattern.

How do you think we can improve the following code?

public function testGetPageHieratchyAsXml()
{
    crawler()->addPage($root, PathParser()->parse("PageOne"));
    crawler()->addPage($root, 
       PathParser()->parse("PageOne.ChildOne"));
    crawler()->addPage($root, PathParser()->parse("PageTwo"));

    request()->setResource("root");
    request()->addInput("type", "pages");

    $responder = new SerializedPageResponder();
    $response = $responder->makeResponse(
        new FitNesseContext($root), $request
    );

    $xml = $response->getContent();

    assertEquals("text/xml", $response->getContentType());
    assertSubString("<name>PageOne</name>", $xml);
    assertSubString("<name>PageTwo</name>", $xml);
    assertSubString("<name>ChildOne</name>", $xml);
}

public function testGetPageHieratchyAsXmlDoesntContainSymbolicLinks()
{

    $pageOne = crawler()->addPage($root, 
       PathParser()->parse("PageOne"));

    crawler()->addPage($root, 
       PathParser()->parse("PageOne.ChildOne"));
    crawler()->addPage($root, PathParser()->parse("PageTwo"));

    $data = $pageOne->getData();

    $properties = $data->getProperties();
    $symLinks = $properties->set(SymbolicPage::PROPERTY_NAME);

    $symLinks.set("SymPage", "PageTwo");
    $pageOne.commit($data);
    request()->setResource("root");
    request()->addInput("type", "pages");

    $responder = new SerializedPageResponder();
    $response = $responder->makeResponse(
        new FitNesseContext($root), $request);

    $xml = $response->getContent();

    assertEquals("text/xml", $response->getContentType());
    assertSubString("<name>PageOne</name>", $xml);
    assertSubString("<name>PageTwo</name>", $xml);
    assertSubString("<name>ChildOne</name>", $xml);
    assertNotSubString("SymPage", $xml);
}

public function testGetDataAsHtml()
{
    crawler()->addPage($root, PathParser()
           ->parse("TestPageOne"), "test page");
    request()->setResource("TestPageOne");
    request()->addInput("type", "data");
    $responder = new SerializedPageResponder();
    $response = $responder->makeResponse(
        new FitNesseContext($root), $request);
    $xml = $response->getContent();
    assertEquals("text/xml", $response->getContentType());
    assertSubString("test page", $xml);
    assertSubString("<Test", $xml);
}

This is how we can improve it:

public function testGetPageHierarchyAsXml()
{
    makePages("PageOne", "PageOne.ChildOne", "PageTwo");
    submitRequest("root", "type:pages");
    assertResponseIsXML();
    assertResponseContains("<name>PageOne</name>", "<name>PageTwo</name>", "<name>ChildOne</name>");
}

public function testSymbolicLinksAreNotInXmlPageHierarchy() 
{
    $page = makePage("PageOne");
    makePages("PageOne.ChildOne", "PageTwo");
    addLinkTo($page, "PageTwo", "SymPage");
    submitRequest("root", "type:pages");
    assertResponseIsXML();
    assertResponseContains("<name>PageOne</name>", "<name>PageTwo</name>", "<name>ChildOne</name>");
    assertResponseDoesNotContain("SymPage");
}

public function testGetDataAsXml()
{
    makePageWithContent("TestPageOne", "test page");
    submitRequest("TestPageOne", "type:data");
    assertResponseIsXML();
    assertResponseContains("test page", "<Test");
}

The benefit of this pattern is that the vast majority of annoying details have been eliminated. The tests get right to the point and use only the data types and functions that they truly need. Anyone who reads these tests should be able to understand what they do very quickly, without being misled or overwhelmed by details.

#4 Single Responsibility and Error Handling

The best way to describe this is to quote directly from the book:

Functions should do one thing. Error handing is one thing. Thus, a function that handles errors should do nothing else. This implies that if the keyword try exists in a function, it should be the very first word in the function and that there should be nothing after the catch/finally.

#5 Better Error Handling

how do you think this piece of code can get better shaped?

$port = new ACMEPort(12);
try {
    $port->open();
} catch (DeviceResponseException $e) {
        reportPortError($e);
        logger()->log("Device response exception", $e);
    } catch (ATM1212UnlockedException $e) {
        reportPortError($e);
        logger()->log("Unlock exception", $e);
    } catch (GMXError $e) {
        reportPortError($e);
        logger()->log("Device response exception");
    } finally {
        /// ...
}

We can simplify our code considerably by wrapping the API that we are calling and making sure that it returns a common exception type:

$port = new LocalPort(12);

try {
    $port->open();
} catch (PortDeviceFailure $e) {
    reportError($e);
    logger()->log($e->getMessage(), $e);
} finally {
    // ...
}
class LocalPort {

    private $innerPort;

    public function __construct(int $portNumber) {
        $this->innerPort = new ACMEPort($portNumber);
    }

    public function open() {
        try {
            $this->innerPort->open();
        } catch (DeviceResponseException $e) {
            throw new PortDeviceFailure($e);
        } catch (ATM1212UnlockedException $e) {
            throw new PortDeviceFailure($e);
        } catch (GMXError $e) {
            throw new PortDeviceFailure($e);
        }
    }

    // ...
}

Wrappers like the one we defined for ACMEPort can be very useful.

Okay. This is it for this part. I’ll continue posting the next parts soon. You can join my Telegram channel to get notified of the latest posts. Also, you can follow me on Twitter and LinkedIn.

A Few Words on Webhooks

Mehrad Sadeghi — Mon, 01 Aug 2022 18:58:00 +0000

In 2006 during working on a startup, Jeff Lindsay wrote about an architectural pattern he called “webhooks”. Since then almost all web developers have heard this term.

I think webhooks are mostly based on the Observer design pattern. Observer is a pattern where an observer is observing (looking) for an event to be fired. The important part here is that the observer is not polling anything, It registers itself to the origin to get notified when the desired event happens.
Polling is another method where the destination is checking for new changes in origin constantly, As opposed to what the observer pattern does.

Webhooks are very similar to observers. A webhook is basically an endpoint that should be notified (called) when an event is dispatched. This approach is better than the “Polling” method in most cases. It is faster and uses less resource.

So by webhooks, Applications can use a so-called “hook”, To send automated messages to each other when something (an event) happens. For example, When you buy a product online, You receive an email or an SMS. What happens here is that the email or SMS provider provides an endpoint (in this context a webhook) and the store calls this endpoint when for example an order is placed.

You can learn more about webhooks in this crash course on youtube.

Laravel CRUD Generator

Mehrad Sadeghi — Tue, 22 Sep 2020 15:56:00 +0000

Laravel CRUD Generator is a simple and light-weight wrapper on Laravel's default controller generator, Which makes creating a controller with a pre-defined CRUD like a breeze.

You can define your validation rules in an interactive way that crud-generator provides. Also it is compatible with Laravel 5.x, 6.x, 7.x, 8.x and 9.x.

There is demo available here which is showing how it's done :)

Installation

$ composer require mehradsadeghi/laravel-crud-generator

Usage

It works based on your $fillable property of the target model.

If you would like to use $guarded instead of $fillable, It is supported too. In that case you'll need to have an existing Schema (table), Then the crud generator will automatically figures out your fillables.

As an example:

$ php artisan make:crud UserController --model=User

If you would like to have validaiton rules too, You may enter the --validation option:

$ php artisan make:crud UserController --model=User --validation

Customizing Default Stubs

It is possible to publish default stubs and change them in a way that fulfills your requirements.

In order to do this:

$ php artisan crud:publish

The published stubs will be located within stubs/crud directory in the root of your application. Any changes you make to these stubs will be reflected when you generate crud.

Feel free to take a look at crud-generator repository.

How To Filter Your Eloquent Queries Based on URL Query String in Laravel Like a Pro

Mehrad Sadeghi — Fri, 31 Jul 2020 17:50:00 +0000

Describing the Problem

You have probably faced the situation where you needed to filter your query based on given parameters in url query-string and after developing the logics, You've had a code-base like what we can in the above image.

This approach works, But it's not a good practice.

When the number of parameters starts to grow, The number of these kind of if statements also grows and your code gets huge and hard to maintain.

Also it's against the Open/Closed principal of SOLID principles, Because when you have a new parameter, You need to get into your existing code and add a new logic (which may breaks the existing implementations).

So we have to design a way to make our filters logics separated from each other and apply them into the final query, which is the whole idea behind the package I wrote for Laravel.

Laravel Filter Query String

First you need to install the package:

$ composer require mehradsadeghi/laravel-filter-querystring

Then you should use the FilterQueryString trait in your model, And define $filters property which can be consist of available filters or your custom filters.

use Mehradsadeghi\FilterQueryString\FilterQueryString;

class User extends Model
{
    use FilterQueryString;

    protected $filters = [];

    ...
}

Then you need to use filter() method in your eloquent query. For example:

User::select('name')->filter()->get();

Available Methods

Sort
Comparisons
In
Like
Where clause

For the purpose of explaining each method, Imagine we have such data in our users table:

id	name	email	username	age	created_at
1	mehrad	mehrad@example.com	mehrad123	20	2020-09-01
2	reza	reza@example.com	reza123	20	2020-10-01
3	hossein	hossein@example.com	hossein123	22	2020-11-01
4	dariush	dariush@example.com	dariush123	22	2020-12-01

And assume our query is something like this:

User::filter()->get();

Sort

Sort is the equivalent to order by sql statement which can be used flexible in FilterQueryString:

Conventions:

?sort=field
?sort=field,sort_type
?sort[0]=field1&sort[1]=field2
?sort[0]=field1&sort[1]=field2,sort_type
?sort[0]=field1,sort_type&sort[1]=field2,sort_type

In User.php

protected $filters = ['sort'];

Single sort:

https://example.com?sort=created_at

Output:

name	email	username	age	created_at
mehrad	mehrad@example.com	mehrad123	20	2020-09-01
reza	reza@example.com	reza123	20	2020-10-01
hossein	hossein@example.com	hossein123	22	2020-11-01
dariush	dariush@example.com	dariush123	22	2020-12-01

Note that when you're not defining sort_type, It'll be asc by default.

Multiple sorts:

https://example.com?sort[0]=age,desc&sort[1]=created_at,desc

Output:

name	email	username	age	created_at
dariush	dariush@example.com	dariush123	22	2020-12-01
hossein	hossein@example.com	hossein123	22	2020-11-01
reza	reza@example.com	reza123	20	2020-10-01
mehrad	mehrad@example.com	mehrad123	20	2020-09-01

Comparisons

Comparisons are consist of 6 filters:

greater
greater_or_equal
less
less_or_equal
between
not_between

Conventions:

?greater=field,value
?greater_or_equal=field,value
?less=field,value
?less_or_equal=field,value
?between=field,value1,value2
?not_between=field,value1,value2

In User.php

protected $filters = [
    'greater',
    'greater_or_equal',
    'less',
    'less_or_equal',
    'between',
    'not_between'
];

Example of greater:

https://example.com?greater=age,20

Output:

name	email	username	age	created_at
hossein	hossein@example.com	hossein123	22	2020-11-01
dariush	dariush@example.com	dariush123	22	2020-12-01

Example of not_between:

https://example.com?not_between=age,21,30

Output:

name	email	username	age	created_at
mehrad	mehrad@example.com	mehrad123	20	2020-09-01
reza	reza@example.com	reza123	20	2020-10-01

In

In clause is the equivalent to where in sql statement.

Convention:

?in=field,value1,value2

In User.php

protected $filters = ['in'];

Example:

https://example.com?in=name,mehrad,reza

Output:

name	email	username	age	created_at
mehrad	mehrad@example.com	mehrad123	20	2020-09-01
reza	reza@example.com	reza123	20	2020-10-01

Like

Like clause is the equivalent to like '%value%' sql statement.

Conventions:

?like=field,value
?like[0]=field1,value1&like[1]=field2,value2

In User.php

protected $filters = ['like'];

Single like:

https://example.com?like=name,meh

Output:

name	email	username	age	created_at
mehrad	mehrad@example.com	mehrad123	20	2020-09-01

Multiple likes:

https://example.com?like[0]=name,meh&like[1]=username,dar

Output:

name	email	username	age	created_at
mehrad	mehrad@example.com	mehrad123	20	2020-09-01
dariush	dariush@example.com	dariush123	22	2020-12-01

Where Clause (default filter)

Generally when your query string parameters are not one of previous available methods, It'll get filtered by the default filter which is the where sql statement. It's the proper filter when you need to directly filter one of your table's columns.

Conventions:

?field=value
?field1=value&field2=value
?field1[0]=value1&field1[1]=value2
?field1[0]=value1&field1[1]=value2&field2[0]=value1&field2[1]=value2

Assuming we want to filter name, username and age database columns, In User.php

protected $filters = ['name', 'username', 'age'];

Example:

https://example.com?name=mehrad

Output:

name	email	username	age	created_at
mehrad	mehrad@example.com	mehrad123	20	2020-09-01

Example:

https://example.com?age=22&username=dariush123

Output:

name	email	username	age	created_at
dariush	dariush@example.com	dariush123	22	2020-12-01

Example:

https://example.com?name[0]=mehrad&name[1]=dariush

Output:

name	email	username	age	created_at
mehrad	mehrad@example.com	mehrad123	20	2020-09-01
dariush	dariush@example.com	dariush123	22	2020-12-01

Example:

https://example.com?name[0]=mehrad&name[1]=dariush&username[0]=mehrad123&username[1]=reza1234

Output:

name	email	username	age	created_at
mehrad	mehrad@example.com	mehrad123	20	2020-09-01

Custom Filters

By custom filters you can define your own methods as filters. This helps with the Open/Closed of SOLID principles, Hence each time a new filter is needed, you don't have to edit previous filters and you can just write a separate method for it.

Let's create a custom filter. Assuming you want to create a filter named all_except which retrieves all users except the one that is specified:

In User.php

protected $filters = ['all_except'];

public function all_except($query, $value) {
    $query->where('name', '!=', $value);
}

To test our newly added filter:

https://example.com?all_except=mehrad

Output:

name	email	username	age	created_at
reza	reza@example.com	reza123	20	2020-10-01
hossein	hossein@example.com	hossein123	22	2020-11-01
dariush	dariush@example.com	dariush123	22	2020-12-01

Note that your custom defined filters have the most priority which means you can even override available filters.

For example lets change in filter in a way that only accepts 3 values:

In User.php

protected $filters = ['in'];

public function in($query, $value) {

    $exploded = explode(',', $value);

    if(count($exploded) != 4) {
        // throwing an exception or whatever you like to do
    }

    $field = array_shift($exploded);

    $query->whereIn($field, $exploded);
}

Another good example for custom filters are when you don't want to expose your database table's column name. For example assume we don't want to expose that we have a column named username in users table:

In User.php

protected $filters = ['by'];

public function by($query, $value) {
    $query->where('username', $value);
}

https://example.com?by=dariush123

Output:

name	email	username	age	created_at
dariush	dariush@example.com	dariush123	22	2020-12-01

Minor Tip

In order to prevent your model to get messy or populated with filter methods, You can create a trait for it and put everything about filters inside the trait.

You can also take a look at Laravel Filter Query String GitHub repo.