Skip to content

Code Organization#

Organizing your code effectively is critical for developing maintainable, scalable, and efficient Miva Merchant templates. By adhering to consistent structure and best practices, you can enhance readability, reduce errors, and streamline collaboration with other developers.

This guide builds upon the principles of “Clean Code,” focusing on readability, simplicity, and maintainability, inspired by Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin.

General Rules#

Follow Standard Conventions#

  • Adhere to the coding standards defined in Miva’s Code Standards.
  • Ensure consistency in naming, formatting, and structure across the entire codebase.

Keep It Simple (KISS)#

  • Simplify your code whenever possible.
  • Avoid unnecessary complexity.

“Everything should be made as simple as possible, but not simpler.”

– Albert Einstein

Don’t Repeat Yourself (DRY)#

  • Eliminate duplication by abstracting repetitive code into reusable components.
  • Refactor code whenever you find similar logic repeated.

Example:

Incorrect

<mvt:if expr="g.page EQ 'HOME'">
    <!-- Home page logic -->
</mvt:if>
<mvt:if expr="g.page EQ 'ABOUT'">
    <!-- About page logic -->
</mvt:if>

Correct

<mvt:assign name="l.is_target_page" value="g.page EQ 'HOME' OR g.page EQ 'ABOUT'" />
<mvt:if expr="l.is_target_page">
    <!-- Shared logic for target pages -->
</mvt:if>

The Boy Scout Rule#

  • Leave the code cleaner than you found it.
  • Continuously refactor to prevent “code rot.”

“It’s not enough to write the code well. The code has to be kept clean over time.”

– Robert C. Martin

Always Find Root Cause#

  • Address the root cause of issues rather than applying “quick fixes.”
  • Avoid introducing “band-aid” solutions that accumulate technical debt.

Design Rules#

Keep Configurable Data at High Levels#

Incorrect

<mvt:assign name="s.null" value="file_overwrite('/path/to/export/file.txt', 'data', l.file_data)" />

Correct

<mvt:assign name="l.EXPORT_FILE_PATH" value="'/path/to/export/file.txt'" />
<mvt:assign name="s.null" value="file_overwrite(l.EXPORT_FILE_PATH, 'data', l.file_data)" />

Avoid Over-Configurability#

  • Reduce the number of decisions required to use a framework or function.
  • Maintain flexibility while adhering to “convention over configuration.”

Further Reading:

Understandability Tips#

Be Consistent#

  • Use the same vocabulary and patterns for similar types of variables and functions.

Incorrect

<mvt:assign name="l.user_first_name" value="'John'" />
<mvt:assign name="l.shopper_last_name" value="'Doe'" />
<mvt:assign name="l.customer_full_name" value="l.user_first_name $ ' ' $ l.shopper_last_name" />

Correct

<mvt:assign name="l.customer:first_name" value="'John'" />
<mvt:assign name="l.customer:last_name" value="'Doe'" />
<mvt:assign name="l.customer:full_name" value="l.customer:first_name $ ' ' $ l.customer:last_name" />

Use Explanatory Variables#

  • Break complex expressions into intermediate variables with meaningful names.

Incorrect

<mvt:assign name="l.formatted_date" value="time_t_year(s.time_t, 'local') $ '-' $ padl(time_t_month(s.time_t, 'local'), 2, 0) $ '-' $ padl(time_t_dayofmonth(s.time_t, 'local'), 2, 0)" />

Correct

<mvt:assign name="l.timezone" value="'local'" />
<mvt:assign name="l.year" value="time_t_year(s.time_t, l.timezone)" />
<mvt:assign name="l.month" value="padl(time_t_month(s.time_t, l.timezone), 2, 0)" />
<mvt:assign name="l.formatted_date" value="l.year $ '-' $ l.month" />

Avoid Negative Conditionals#

  • Express conditionals positively whenever possible.

Incorrect

<mvt:assign name="l.is_logged_out" value="g.Basket:cust_id EQ 0" />
<mvt:if expr="NOT l.is_logged_out">
    <!-- Logged-in logic -->
</mvt:if>

Correct

<mvt:assign name="l.is_logged_in" value="g.Basket:cust_id GT 0" />
<mvt:if expr="l.is_logged_in">
    <!-- Logged-in logic -->
</mvt:if>

Summary#

Adhering to clean code principles ensures that your Miva templates are:

  • Readable
  • Maintainable
  • Scalable

By following these best practices, you can improve the quality and longevity of your codebase, fostering collaboration and efficiency in development.