“The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent.”

Uncle Bob

Practicing our professional life in writing clean code we forget to define clean interfaces between client and server sides.

I would like to write some rules, which I use by development, to make my work and the work of my colleagues easier in the future. Unfortunately, Uncle Bob did not mention this topic in his “Clean Code”.

• Use meaningful names for JSON keys;
• Do not put HTML without strong reason for it;
• Avoid excessive or unnecessary nesting;
• Try to use limitations on number of elements of your services (pagination with start and limit params, filters);
• Split the interfaces to small controllers and actions with meaningful names and structure/nesting;
• Do not repeat yourself in JSONs;
• Try to keep your JSON simple, stupid;

Use meaningful names for JSON keys.

We spend time on naming our variables, classes… functions. Thus, let us do the same for JSON structure and keys, and let us make JSON human readable as well.

Do not put HTML without strong reason for it.

Front End side is responsible as an interface between humans and machines. Let us not delegate this function on Back End; exception is a text (user comments, which were generated with WYSIWYG editors).

Avoid excessive or unnecessary nesting

Nesting is often used to present some meta information. For example, in the service, which is used to get the list of books, not only the author of the book but also his short biography, age, and date of birth can be included. For meta information it would be much better to use separate services.

Try to use limitations on number of elements of your services (pagination with start and limit params)

Small grids make the applications more intuitive and protect your servers from overloading, DDoS attacks, etc.

Split the interface to small controllers and actions with meaningful names and structure/nesting.

We obtain Fat Stupid and Ugly Controllers not only by means of putting the model’s code in the controller but it happens when we forget to put a new action in inappropriate controller. Even if you have one action in the controller it is better to create it instead of adding it to inappropriate controller.

Do not repeat yourself in JSONs.

DRY rule is general and JSONs are not an exception.

Try to keep your JSON simple, stupid

KISS rule is also general.

 

You may disagree with the points I have introduced referring to the server overloading due to the increase in the number of requests and / or bandwidth limitations because of too long key names.

Often behind a dirty, unreadable code there is exactly the optimization of processes, care about resources. I am sure that the optimization problem is solved not at the expense of the quality of the code (requests, in this case), but due to the use of caching technology, DB optimization etc.