1

Functions are the first line of organization in any program.I believe writing them well improves the readability of code to some extent.I am working on metrics that describe how readable the function or class is ?. One such metric that contribute to readability is Function should do only one thing from clean coders book by Robert C Martin.

To encode the above metric into the program, the features I used was

  • a long list of parameters,
  • lines of code,
  • no of function calls.
  • no of local variables in a function
  • no of loops in a function

Is there any other features that need to be included apart from above chosen features ?. If so, can anyone suggest me what other features can be included, please ?

Can anyone suggest or give any hints on other metrics that measure the readability of the function or class apart from the metric `function should do only one thing.

If my question seems absurd, Pardon me, I am a beginner in this field. There are a lot of tools available on metrics, but I looking for metrics specific to readability.And please forgive me for adding unnecessary tags, i don't know the apt tag for this question. Any hints or suggestions would be greatly helpful.

  • 1
    Cyclomatic Complexity (en.wikipedia.org/wiki/Cyclomatic_complexity) handles your last three items into one metric. It's useful to find outliers in your code. Another metric that Visual Studio includes is the Maintainability Index (projectcodemeter.com/cost_estimation/help/…) which combines cyclomatic complexity, lines of code, and Halstead volume (projectcodemeter.com/cost_estimation/help/GL_halstead.htm) which essentially gets all of those together in one metric. – Berin Loritsch Jun 27 '18 at 23:49
  • That said, you'll find that in some cases you'll have code that violates whatever thresholds you put on your metrics. That's OK when you can justify it. One of the ways of increasing readability is to consolidate blocks of code into other methods/functions called from your method. I think that particular metric might give you a few red herrings (false indicators). – Berin Loritsch Jun 27 '18 at 23:53
  • please don't cross-post: stackoverflow.com/questions/51069667/… "Cross-posting is frowned upon as it leads to fragmented answers splattered all over the network..." – gnat Jun 28 '18 at 4:55
  • 1
    There is a good reason for the answer to softwareengineering.stackexchange.com/questions/141005/… being "you need to ask your peer reviewer. That is the only useful "metrics", so better stop wasting your time looking for braindead "readibility" rules, there are none, you need another programmer for this. – Doc Brown Jun 28 '18 at 5:31
  • 3
    None of these metrics measure readability. Readability is a topic many people preach about, yet no one measures or tests it in any formal way. The connection between any of those metrics and readability is pure speculation. – Frank Hileman Jun 29 '18 at 16:04
1

There are many metrics that can indicate some kind of code quality or aspects of readability, but in the end they don't matter. What matters is that the intended audience of the code (i.e. other humans) can understand the code easily. Different audiences have different skill levels, different backgrounds, and different expectations, so there isn't one style that can satisfy them all.

This doesn't mean that metrics are useless, just that we should be aware how they are just proxies for actual readability. One classic example is cyclomatic complexity (CC), which counts the branches in a function. What are various problems with CC?

  • In case of a switch/case statement, CC is equal to the number of cases, as if it were written as an if/else-if/else cascade. However, humans tend to perceive a switch/case as much simpler.
  • Also, CC cannot really account for exception flow, as every subexpression that could throw is effectively a branch point. Yet, many people perceive exceptions as much simpler than a conditional for every operation that could fail, and exceptions are typically ignored when calculating CC (but how should try/catch be considered?)
  • There are also some control flow operators that are often not perceived as control flow, such as short-circuit operators as in if (a && b), or safe navigation operators like foo.?bar (e.g. in C#).
  • Some control flow may be hidden by higher-order functions, e.g. compare the loops for x in things: foo(x) with the largely equivalent map(foo, things).

There are metrics that try to address some of these concerns, e.g. Cognitive Complexity by SonarQube.

Static analysis tools like linters and style checkers use various metrics to alert you of possible issues. They may operate on a purely syntactic level (e.g. pycodestyle), others perform semantic analysis (e.g. findbugs operates on compiled Java bytecode, not on source code). Many perform a combination, and e.g. operate on a parsed representation of the source code. For dynamic languages, linters might also perform some amount of type checking. A style checker might be able to match your source against known patterns than can be replaced with a more elegant alternative, or when the pattern is likely a bug.

In the development work I'm currently doing (Python), I find the following checks or metrics most helpful:

  • a basic style check that enforces consistent formatting and naming (flake8)
  • simple semantic checks, such as complaining when a variable is assigned but not used, or when I call a function that doesn't exist (flake8, pylint)
  • an external type check (mypy)
  • simple test coverage metrics (statement coverage) (pytest-cov)

None of these put a number on how good my code is, but they help me to find and prevent problems. There are similar freely available tools for Java, e.g. checkstyle. These tools typically define policies and not metrics, but a policy might be that a metric should be within a certain bound (e.g. less than 20 local variables in scope).

It is worth reading the documentation for some of these tools to see which aspects of readability they try to measure or which issues they try to detect.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.