Should you /* comment */ on kata solutions?

[Mario-paul]

I like to go back to my kata solutions once in awhile to check something I did in the past, and that I might need in order to solve something today. Is it good practice to comment out your solutions explaining the logic in your code or is that to be avoided? I noticed no one ever does this and was wondering why?

[ejini6969]

Ofc, it is. It would be very helpful for learners especially on hard-level katas (blues and purples)

[JohanWiltink]

Yes, it's good practice. Someone else might not immediately see through the code to understand its intent, and that someone else might be you six months from now. ( I myself have certainly been on both ends of this phenomenon. )

So why don't we do it? Laziness, and a chronic tendency to overestimate how self-explanatory our code is. Often, our code fits the way we reason about a problem, so the code will make more sense to ourself than to someone who might reason differently about the same problem, but even then reasoning backwards from code to problem can be harder than reasoning from problem to code.

Including a high-level description of the approach taken to solve a particular problem is A Good Thing.

If you are going to comment -- i is the index counter on every loop over a list - well, don't. At low level, your code should be self-explanatory ( "self-commenting" ).
But certain implicit conventions, like i is an index, r is the result being built, t is a temporary value with very local scope, xss is a list of lists of xs, might need making explicit if they're unusual in whatever environment you're using them.

[Rex-Gardner]

No one likes comments in production, because it can become outdated sometime. But comments are good practice for complex custom solutions in trainings. You can return later to them and easyly remember what did you write.