DEV Community 👩‍💻👨‍💻

Discussion on: The ONE book every developer MUST read!

tomasforsman profile image
Tomas Forsman

The problem is that even if you write perfectly you have to consider different people reading your code as well and what you find clear I might find confusing and vice versa. I comment, not for me or people that read code like me, but for people that read code differently.

Basically it's like explaining things that I know is not general knowledge or common practise. Like I would do when writing any text.

It's like When Max Thunberg, a friend of mine, is to read my code. Well, not really, just wrote that sentence to demonstrate that while I and people around me know who I meant I had to comment on who Max is to clarify for others. The same could be true when, as an example, I'd call an API. If I used an unconventional way to save memory I'd also comment on why I didn't follow conventions.

Another reason is to speed up on boarding of junior developers or just developers coming from other languages.

Yet another reason could be to help none coders, like customers, understand the code.

Lastly I have dyslexia and for me comments makes code more readable even when I don't read them simply by breaking up the code, giving me visual anchors.

So,while I agree with the notion that comments are failures to express ourself clearly enough through code I also believe that to be an impossible task.

This could be a nice code challenge, to take a piece of commented code and refactoring it without comments in a way that's more clear and then discuss the different solutions.

Thread Thread
kevtiq profile image
Kevin Pennekamp

This is such a valuable view! Inclusiveness is so important for designers, but we developers forget it. Everybody must be as good as us, our code should tell everything. But someone with dyslexia, or someone not proficient in English, or even beginners will have a hard time if we do not take them into consideration

Some comments have been hidden by the post's author - find out more