Clojurians Log v2

> it's clearer to say "this code meets its design objectives" than to say "this code is beautiful" These may be orthogonal concerns: "design objectives" is often convoluted with "fit for use/purpose"; we as software developers often conflate "self-consistency" in a program/design/abstraction with "correctness". It's not surprising, as the former can be studied as a closed model, while the latter requires additional context and assumptions from the interactions with things outside of our model.

I don't think software beauty is completely subjective to my aesthetic senses; we may have simply not developed the correct notation and semantics to talk about it intelligently. Perhaps, we should be looking to mathematics (https://en.wikipedia.org/wiki/Mathematical_beauty), or other existing fields of study, for inspiration.

> To attempt to measure code quality, one must have a concrete and unambiguous definition to work with, > I think that's a faulty assumption. I believe quality is inherently subjective and objective. Subjective judgement is essential for quality. But quality is more than opinion, therefore it has an objective aspect. > Without getting too philosophical, perhaps code quality is purely subjective, but that also seems a bit wrong intuitively. > I'd actually recommend reading into philosophy to learn about quality. • Zen and the art of motorcycle maintenance (novel with a philosophical theme) touches on the subjective and objective aspects of quality • Phenomenology is the philosophical study of people's experiences. It escapes previous attempts to view human experience as purely objective. https://en.m.wikipedia.org/wiki/Phenomenology_(philosophy)

I'm under the impression that Zach Tellman has a good understanding of quality in software. Elements of Clojure isn't about quality exactly, but I believe it's based on a good understanding about what quality is. https://elementsofclojure.com/

I think “utility is contextual” is a good place to start. Then try to tease apart quality as something that lasts longer than utility.

Very curious to hear other people’s thoughts about this. I find that the average quality of stuff in the Clojure community is better than elsewhere. Which I appreciate greatly!

I've also posted https://www.linkedin.com/feed/update/urn:li:activity:7102949390142644224/.

Utility! That's a good point. I think integrity [as in whole and undivided] (or congruence) and preferability [as in better] are also central components of quality, i.e., that the thing exhibits coherence and consistency on its own and is preferable to other similar things when people are presented with a choice.

There are few pithy sayings that are short, memorable, and maybe a little useful: • bad programmers ignore details and bad designers get lost in them - Nate Kirby • Make the common case easy and the complex case possible - derivative of an Alan Kay quote One of the first questions I ask when evaluating a library is "where's the data?". It's a very common mistake to write a ton of code and not have a clear model of the domain explicitly defined anywhere. A missing data model is often a sign that the domain isn't well understood. I think that's one of the reasons that clojure programs tend to be easy to work with. They're data oriented. While there is some subjectivity, I think there are properties of programs and designs that can be broken down and talked about concretely. • coupling • cohesion • brittleness • efficiency/performance • implicit vs explicit Another common mistake is to weakly define priorities. I really like the problems slide from the https://www.youtube.com/watch?v=2V1FtfBDsLU.

Whoops, accidentally hit send before I was done. Anyway, a good API let's you focus (explicitly) on what is important for your use case and ignore the parts that don't matter (make them implicit). A bad API requires you to focus on incidental problems and only gives you implicit access to the things you care about.

As the slide indicates, the most important problems are related to understanding the domain. It seems obvious, but it's very easy to find libraries where the author doesn't fully understand the domain.

I think coupling can be measured by analyzing the code to uncover outgoing and incoming "connections," i.e., "efference" and "afference," as @msolli has previously suggested in one of our recent discussions in #clojure-norway. Those might be useful metrics. I don't know how to measure the cohesion of a software system. As for brittleness, I suppose one way to measure that would be to analyze the history of the source code to see how frequently it changes. If it changes frequently, then perhaps that would be a good indicator or proxy metric for brittleness. Efficiency and performance can be measured through benchmarks, etc. I'm not sure how to measure "implicit vs. explicit." I feel like one thing missing is whether the code does what the programmer intended (and does not do what the programmer did not intend) and that the software product as a whole does what the user expects in the most intuitive way. I think that's what @teodorlu might have had in mind when suggesting utility as a relevant concept above. But that feels exceedingly difficult to measure.

Effectiveness might be a different term for utility, i.e., "It does the correct [useful] thing." Efficiency being its cousin, "It expends the least amount of energy while doing the thing." We should want things to be both effective and efficient.

I think you can talk about quality in a rigorous way, but I don't think there's any generic program that can give a score for "author understands the domain" or "software was written with the business' goals and resources in mind".

Yeah, I think that kind of "higher-order quality" is inherently subjective and perhaps unmeasurable.

I wouldn't say it's unmeasurable. It seems like it would be totally reasonable to measure quality by asking a panel of experts to give a 1-10 score or something (that's not the only method, but just an example).

Yes, it might be possible to measure it by observing how the user interacts with the program, collecting and analyzing huge amounts of usage data, conducting user surveys, user groups, one-on-one user interviews, etc.

Maybe it's useful to separate between the quality of our craft and the quality of the end result itself. I suppose it's possible to craft something beautiful from the perspective of the craftspeople that is useless or uninteresting to "outsiders."

And I suppose it's also possible to create something that is entertaining, useful, or interesting to "outsiders" that is horrendous from the perspective of the craftspeople.

Trying to discuss the "internal quality" and "external quality" of something at the same time might be confusing, although I suspect there's a strong correlation between them, i.e., "external quality" tends to move in tact with "internal quality."

But it might be that developers who focus on "internal quality" are also more intentional about their decisions and more attentive to "external quality."

That's a very utilitarian perspective. There is no good, only good for. I think that's one of the points of the Effective Programs talks is that clojure is designed for "situated programs". It doesn't make sense to evaluate software without respect to some set of goals or set of stakeholders.

There could be interesting comparisons between code, writing (prose), visual arts, and music. To a programmer, code could be aesthetically pleasing, even if it doesn't do anything beneficial. We can look at different implementations of the same program and say that one is "better" than the other, even if the performance characteristics and output are identical.

That sounds a little too hand wavy to me. I think a more rigorous approach is to evaluate quality against a set of goals or objectives. Maybe the goal is intellectual elegance and church numerals are great, but maybe the goal is optimizing frames per second and church numerals are bad. I think the subjectivity is mostly about choosing which goals and objectives to focus on and less about which design decisions best address those goals. There may be disagreement about which design decisions work best, but there's usually at least some way to measure the result after the fact.

> Another common mistake is to weakly define priorities. One easy way to make the wrong tradeoffs is to not set goals or objectives in the first place.

I’m happy to accept that elegance and aesthetics describe quality in part — though it doesn’t give the full picture (it misses utility).

https://www.youtube.com/watch?v=5TFDG-y-EHs vs https://elixir.bootlin.com/glibc/glibc-2.30/source/stdlib/exit.c

Setting aesthetics as an explicit non-goal seems like a workaround for having the wrong aesthetic to me.

Haha, I love it. "I want my code to look shit." Thereby, the more shit it looks, the better it is.

making aesthetics a non-goal doesn't mean that making it uglier is better. It just means that it's not a factor. code golf is a canonical example.

The only metric is code size. How it looks is unimportant.

I think that is a goal of some toy languages like https://en.wikipedia.org/wiki/Brainfuck and https://en.wikipedia.org/wiki/Whitespace_(programming_language). They are obscure and "bad" by design.

To summarize, one foundational aspect of code quality is how well it realizes the defined goals.

Also, since there can be multiple sets of goals, it follows that there are multiple code qualities.

Some notes: • It's typically not code that ships, but some derived artifact • code can be broken down into smaller units that might be easier to analyze: ◦ libraries ◦ namespaces ◦ functions ◦ services ◦ design decisions

I’d claim that in code golf, there’s beauty to be found in concise, terse solutions to problems.

Right. You could define beauty that way, but I think it's also fair to say that it's an uncommon definition. I think it would be rare for someone to look at minified javascript and describe it as beautiful. I do think there is beauty in finding solutions that meet desired outcomes, but I think it's clearer to say "this code meets its design objectives" than to say "this code is beautiful" (which may be true, but is open to many different, alternate interpretations).

> You could define beauty that way, but I think it’s also fair to say that it’s an uncommon definition What definition of beauty do you have in mind? (Not that I have a good definition of beauty myself, I find it really hard to define. As with quality. I tend to revert to “I know it when I see it”. Very hard to measure objectively, as we’ve touched on 🙂)

I define beauty as "a combination of features that are pleasing to my aesthetic senses."

I feel like defining beauty in terms of aesthetics is kind of circular, and a bit of cheating 😛

Yeah, I guess it is. Technically, it's a different word, but arguably a synonym 😛

But we could remove the word "aesthetics" from the definition, and it would still work the same: "a combination of features that are pleasing to my senses."

If you want to get really pedantic, I suppose the senses cannot be pleased. The pleasing occurs in the mind when the signals from the senses are interpreted.

And we could continue reducing the sentence until we reach the base level of elementary particles and physics 😂

"Beauty is an effect produced by electrical signals, chemical reactions, and state transitions within a human's brain upon interpreting external stimuli obtained through sensory organs."