Have you heard of the Green Pencil Method in teaching? It is a teaching technique that focuses on highlighting the things done right. Kind of the opposite of your typical teaching approach where teachers give feedback on what went wrong first.
When I first read about this method I thought — “Wow, this is fascinating, this is the opposite of what I know. If only my teachers used it on me I would never be terrified of making mistakes”. Wouldn’t it be awesome if we only focused on the positive side of things?
Yes, you do want to stay positive and you do want to be encouraged by the results of your work. It helps you to do more, to create more. The psychological ramifications of positive feedback are a vast theme that I won’t cover in this article. Overall — if we feel good, we perform better, that’s the point.
But here is the deal. We can’t always stay on the positive side. We are humans and it is in our nature to be wrong, to make mistakes. The most efficient way of learning to avoid making mistakes is to receive feedback — “Hey, this is wrong”. The straightforward, candid feedback is unbeatably efficient and it is used everywhere. Even in… software development! And so in this article, I want to talk about how do we give feedback for code crafting and how do we get the goods of positivity and strictness at the same time.
Linting
Code linting is old… the idea predates most of the popular languages that we have nowadays. Verifying the punctuation and style of your program is something that machines are superb at. The computer won’t slip, it won’t miss a comma when linting the code — it is almost as good as a compiler! Well, you know, many languages combine linting and compiling into one, take a look at Python for example.
Now, let’s see how well linting maps to giving feedback candidly and how does it do on the encouraging side.
Giving feedback? Sure, linting does it for you. Most of the language linters are extremely good at it. Here is a piece of Kotlin code:
If we use a Kotlin linter (https://ktlint.github.io/) on this code we will see:
Looking at line 2 we understand that there is an extra space after pluralize in the function definition. Easy to fix, good report, thank you linter! The feedback has been received!
How about encouraging? How did linter do on helping us, developers, to write more?
I stand on that linters are horrible at that. The linter just told me that I did an error, a violation, basically I was just told — “You did wrong, go fix it”. Imagine having dozens or hundreds of errors like this reported by the linter after you put a lot of time and effort into code writing. Well, this is one more way to get stressed. Not perfect.
Linting in CI
The discouragement exacerbates when we add linting as part of the CI/CD pipeline. Nowadays, CI/CD pipelines are such a common practice, you see them everywhere. And hey, why not put something that is as easily automated as linting is into the pipeline. Surely we don’t want to be delivering bad unformatted code? Let’s just toss linting in and fail the builds on any error.
Failing builds due to linting errors is a bad idea!
Yes — it is easy to add linting to your CI. For example here is a GitHub Actions workflow that lints Kotlin code in a Gradle project:
This is all you need. The plugin in Gradle will do the rest:
Why is this problematic?
Here is why — in this case, CI (and linting) does not help developers to write code. If CI fails on unformatted code, then the only thing it does is tell developers “You did wrong”. Yes, it does it in a very well-versed way, but still, the feedback the developer receives is purely negative. Repeated day by day it has a huge effect on developers’ well-being, developers’ will to write code, developers’ creativity. The developer would have to fight the system, the pipeline, what have you to be able to contribute. This ends with fewer folks wanting to contribute (open-source case) or folks wanting to contribute less than they could.
Can we do better? Yeah, there are ways:
- Do not do linting in CI even if it is easy to add. Sound simple enough, huh? Yes, your code won’t be as pretty as it could be with a strict CI. But is having pretty code more important than the well-being of developers and openness for the contribution? This is the question you will have to answer for your project.
- Do linting, but do it in a “helpful” manner. The idea here is to not simply report the linting issues but also use computers (not people) to automatically fix the issues. For example, for the Kotlin linter from the example above we can use a pre-commit hook like:
This hook will run the ktlintFormat task which automatically fixes the linting issues! By doing so we get both of having clean code in the repository and developers being welcome to contribute.
I like the second approach as it is getting the best of both strictness and helpfulness. There are certain things that ktlintFormat can’t do but hey this is significantly better than asking developers to add a semicolon at the end of the line manually. This is the best way of doing linting.
I want to emphasize this. Please put an effort into making contributions to your project’s codebase as easy and welcoming as possible. This is the difference between “no we won’t let you contribute to our project if you don’t know how to put spaces even if your idea is brilliant” and “everybody, come on in, we will take care of the nitty-gritty things, don’t you worry”.
Be helpful to your contributors, make them want to write the code!
