Maintainability: Clean and Clear Code

[GeorgLink]

We have documentation as a metric, maybe maintainability is also relevant.

Maintainability:

If a stranger can modify your code and fix a bug in less than an hour, it is maintainable.

Test it. Ask someone who is outside of the project to take a look at your code and tell you how clear it is. Not how beautiful your classes and code constructs are—that’s what makes it clean. Instead, ask someone to fix a bug in just 30 minutes and see how they react. You will realize how clear the code is and whether it speaks the language a stranger can understand.

Full reference: https://www.yegor256.com/2018/09/12/clear-code.html

[aserebrenik]

I'm not sure how is this related to D&I: would you like to stress that people with different backgrounds, genders etc should all be able to fix the bug in 30 minutes? This seems to be a rather extreme definition of maintainability as in practice developers would be (more or less) familiar with the code they are expected to maintain...

[GeorgLink]

Thanks Alexander, good question.

Here is my reflection of what I thought:

I was not thinking about diversity here. I assumed that creating an inclusive community involves reducing barriers to participation. I thought this "maintainability test" could indicate one barrier of entry that is intrinsic to the code cleanliness and clarity.

[aserebrenik]

This is a good point; however, "cleanliness and clarity" might be in the eye of the beholder, at least to some extent. Margaret Burnett and her team has worked on GenderMag to identify "gender bugs" in software. Based on differences in problem solving strategies of women and men they have created several personas representing those strategies, e.g., Abby embeds strategies more common among women and Tim embeds strategies more common among men. It might be the case that specific "cleanliness and clarity" aspects of the code make comprehension/maintainability more difficult for Abbys than for Tims.

[GeorgLink]

I like the idea of applying a GenderMag approach beyond the user interface to include source code.

[emmairwin]

Agree with @aserebrenik I think this can be a component of communication, or project place - issue tracker, but stand alone seems a bit odd in context of D&I.

[sgoggins]

My experience maintaining Augur has underscored the role of code readability in DEI work. More readable, understandable structure, which we achieved through refactoring work over the past year, has made it palpably easier to involve new contributors.

[jwflory]

I would propose closing this issue or migrating it to another working group. I understand the perspective on inclusiveness, but looking at other metrics we have produced, this feels unusually oriented towards code.

[germonprez]

I agree with this comment. I'm trying to think about where it would even go (other WG). My inclination is to simply close it.

[jwflory]

Since the idea is almost four years old, I think closing it is alright. If it was more recent, I might suggest transferring it elsewhere, but I think it has had a lot of time to be out there.

Closing as invalid. 🎬