How to use the command 'mh_metric' (with examples)

The ‘mh_metric’ command is a powerful tool designed to calculate and enforce code metrics specifically for MATLAB or Octave code. It is particularly useful for developers who wish to maintain high-quality and consistent codebases by analyzing aspects like complexity, code structure, and other relevant metrics. The tool provides insights into your code, enabling better understanding, optimization, and maintenance of large codebases. More information about the tool can be found at misshit.org .

Use case 1: Print the code metrics for the specified files

Code:

mh_metric path/to/file1.m path/to/file2.m ...

Motivation: You may have specific MATLAB files that you are currently working on and want to ensure they adhere to quality standards. By checking these files individually, you can generate a detailed metric report for each, identifying potential improvements and ensuring quality control for those specific segments of code.

Explanation:

• mh_metric: This initiates the command to calculate code metrics.
• path/to/file1.m path/to/file2.m ...: These are the paths to the specific MATLAB files for which you want to calculate the metrics. Each file is individually analyzed, providing reports on various metrics for each specified file.

Example Output:

File: file1.m
- Lines of Code: 120
- Functions: 5
- Cyclomatic Complexity: 8
- Maintenance Index: 72

File: file2.m
- Lines of Code: 150
- Functions: 7
- Cyclomatic Complexity: 12
- Maintenance Index: 65

Use case 2: Print the code metrics for the specified Octave files

Code:

mh_metric --octave path/to/file1.m path/to/file2.m ...

Motivation: If you are working with Octave files and need to measure their quality or compare them to MATLAB equivalents, this use case allows you to generate a detailed report respecting Octave-specific conventions and constructs. It ensures you leverage the right set of analysis techniques that are tailored specifically for Octave code.

Explanation:

• mh_metric: This runs the metric calculation tool.
• --octave: This flag specifies that the files being analyzed are Octave rather than MATLAB.
• path/to/file1.m path/to/file2.m ...: Paths to the Octave files for which you want to calculate the metrics.

Example Output:

File: file1.m
- Lines of Code: 100
- Functions: 4
- Cyclomatic Complexity: 7
- Maintenance Index: 78

File: file2.m
- Lines of Code: 140
- Functions: 6
- Cyclomatic Complexity: 10
- Maintenance Index: 70

Use case 3: Print the code metrics for the specified directory recursively

Code:

mh_metric path/to/directory

Motivation: When working on larger projects housed in a directory structure, it can be cumbersome to analyze files individually. This use case is invaluable for conducting a comprehensive analysis over the entire set of files within a directory. By analysing the metrics recursively, developers can maintain a high standard of quality across the entire codebase, identifying larger patterns or systematic issues.

Explanation:

• mh_metric: Starts the tool to compute metrics.
• path/to/directory: The path to the directory containing MATLAB or Octave files. The command will recursively enter subdirectories and analyze all relevant files.

Example Output:

Directory: /project/src
- Analyzing 3 files
  - file1.m
  - file2.m
  - file3.m

Summary Report:
- Total Lines of Code: 410
- Total Functions: 15
- Average Cyclomatic Complexity: 9
- Average Maintenance Index: 68

Use case 4: Print the code metrics for the current directory

Code:

mh_metric

Motivation: When you are actively working within a given directory and want a quick analysis of all MATLAB or Octave files without specifying paths, this command swiftly computes metrics, providing immediate feedback. It helps maintain focus on real-time code quality improvements within the current working context.

Explanation:

• mh_metric: Provides an analysis of all MATLAB or Octave files present in the current working directory.

Example Output:

Analyzing files in the current directory...

Summary Report:
- Total Lines of Code: 230
- Total Functions: 10
- Average Cyclomatic Complexity: 11
- Average Maintenance Index: 75

Use case 5: Print the code metrics report in HTML or JSON format

Code:

mh_metric --html|json path/to/output_file

Motivation: Different reporting formats offer varying benefits depending on how you plan to utilize the metrics. HTML reports are ideal for easy viewing and sharing among team members via web interfaces, whereas JSON formats are perfect for automated processes and further data analysis in scripts or applications. This flexibility allows developers to integrate and communicate metrics in a format that best suits their workflow.

Explanation:

• mh_metric: Enacts the metric calculation tool.
• --html|json: Specifies the desired output format - --html for HTML formatted reports and --json for JSON formatted reports.
• path/to/output_file: The file path where the output will be saved, allowing you to refer to or share the report afterward.

Example Output in JSON:

{
  "file1.m": {
    "Lines of Code": 120,
    "Functions": 5,
    "Cyclomatic Complexity": 8,
    "Maintenance Index": 72
  },
  "file2.m": {
    "Lines of Code": 150,
    "Functions": 7,
    "Cyclomatic Complexity": 12,
    "Maintenance Index": 65
  }
}

Conclusion:

The ‘mh_metric’ command serves as a comprehensive tool for analyzing MATLAB and Octave code. By offering various use cases from analyzing individual files to generating reports in different formats, it equips developers with the insights needed to enhance and maintain high-quality code standards. Whether working on small projects or large codebases, ‘mh_metric’ provides valuable metrics to guide effective code management and development practices.