A word for “the number of things you need to know to understand the code”? | Hacker News Reader

A word for “the number of things you need to know to understand the code”?

4 pointsunknownsky6 comments

For example, to understand

if (obj.index == 0 && (f_mode > 3 || state[1] != null))

you need to know * What does obj represent * Under what circumstance does obj have an index of 0 * Why we are interested in that circumstance for what we are trying to achieve * What does f_mode represent * Under what circumstances is f_mode greater than 3 * etc etc etc

You need to know at least 10 things to understand it. However, if we break it up and replace it with

if (Membership.IsExpired)

then we need to know 0 things to understand it.

Is there some sort of principle that represents the number of things you need to know? A sort of Things You Need To Know To Understand This Index? Something that is a countable unit, so that you could say that one block of code has an index of 17 (i.e. you need to know 17 things to understand it) while another block of code has an index of 2?

We could start from a baseline assumption that the reader knows the coding principles themselves. The reader needs to know how an if-statement works, for example, but that would not be included in the index. One might argue about whether more obscure coding tricks should be included in the index or not.

In

  if (Membership.IsExpired)

You still need to know what Membership represents, that it has a IsExpired field, that that is a Boolean, and what it means.

Most of it is in the business domain, though.

You may want to start at https://en.wikipedia.org/wiki/Software_metric, which has links to methods both for estimating complexity before a line of code is written and for estimating complexity of existing code. For the latter, examples are:

  https://en.wikipedia.org/wiki/Halstead_complexity_measures
  https://en.wikipedia.org/wiki/Cyclomatic_complexity

AFAIK most of them estimate the complexity of multiple lines of code/functions/entire programs.

I don’t think there is agreement as to the usefulness of this, and if so, which method is the best, or whether it’s possible to measure software complexity at all (for the latter, I think everybody’s gut feeling says “yes”, but I don’t think every person would even place different program fragments in the same order of complexity (example: foo.map.filter(…) versus a for loop with a nested if. Which one is deemed simpler depends on one’s pre-existing knowledge)

I also think we can only estimate program complexity roughly, and wouldn’t go as far as calling anything a metric.

Clickable:

https://en.wikipedia.org/wiki/Halstead_complexity_measures

https://en.wikipedia.org/wiki/Cyclomatic_complexity

Halstead complexity is about the call graph: the number of possible paths through the code.

Cyclomatic complexity is about the number of 'units of syntax' in the code, which I think is closer to what OP is asking. It uses the terms "operator" and "operand".

In the terminology typically used around parsing code, one way to measure complexity is the number of tokens. In the Halstead terminology that would be both operators and operands. https://en.wikipedia.org/wiki/Lexical_token

Another is the number of symbols. The Wikipedia article is a little abstract: https://en.wikipedia.org/wiki/Symbol_(programming) but in the Halstead terminology would be operands.

(The following is a little hand-wavy because the definition of "symbol" varies.)

Tokens, space delimited: if ( obj . index == 0 && ( f_mode > 3 || state [ 1 ] != null ) )

Symbols: if obj index f_mode state null

versus

Tokens: if ( Membership . IsExpired )

Symbols: if Membership IsExpired

What about depth? What if we said your first sentence was 8 deep. One layer for each reference (obj.index, f_mode, state[1]), +1 layer for each statement: == 0, > 3, != null, &&, and (…).

Giving literature and specific sentences reading levels is similar to what you’re asking.

One expression, such as ‘obj.index’, might itself be very deep: obj.index, object and its properties, function, perhaps what created it, and so on.

I don’t know that ‘depth’ is the word you were looking for, perhaps there’s a fancy scientific word to be found. If I wanted to get into it, I’d look into linguistics research on quantifying comprehension and related topics.

GNU's complexity[1] tool calculates something like what you're talking about for procedures in C programs, and calls the result a "complexity score", although I don't think it accounts for variable names, nor magic integers.

[1] - https://www.gnu.org/software/complexity/manual/complexity.ht...

You might look to psychology’s concepts of “cognitive load” and “working memory”.

I've always called this "self-commenting code". No need to overthink it.

Reply on news.ycombinator.com