Is there a coding standard or some other reason why Rocket.Chat codebase contains very few comments? I always assumed it was just a regrettable aspect of pace of development, community contributions etc that no one got round to it, but something I heard recently suggested the team might actual recommend not to comment code?
I don’t think this is the case. @rodrigo.nascimento @diego.sampaio @guilherme.gazzo maybe one of you can confirm?
Oh, recommending not comment the code? that was unexpected. I’ve never recommended such a thing.
But I have to say I usually don’t comment my code. In part it is because I try to write as simple as I can, so most of the time the comments would be so obvious that I prefer not to write them.
@tim.kinnane are you talking about comments you may find on the “middle” of the code or like function documentation?
@diego.dorgam I think just in general.
For instance someone working on the code, if they wanted to, let’s say figure out the purpose of the renderMessage callback would need to read through where it’s used currently to figure out what it does, or read the callback definition to see how to use it.
And even then that’s just a guess based on what you have seen. It wasn’t until a few weeks ago someone told me there was a priority field that it would accept because I missed that when looking through how it works.
Some comments or documentation around some of the larger functions/call backs would go a long way
Yeah I’m surprised how many times I found code without any comments at all, inline or at the start of a block. I honestly can’t remember where I heard or saw it mentioned that gave me the idea it was discouraged, but I did. Might have been just one persons opinion.
I don’t think it matters how simple code is, it’s always helpful to have some comments to hasten the newcomers understanding of the purpose of a function or catch them up on some extra context that will help overcome the challenges you’ve already faced.
It’s surprising how many times I encounter huge blocks of code within Rocket.Chat that have no comments, no documentation and occasionally will do something bizarre like return undefined when the arguments were wrong, instead of throwing an error with a message. It’s like the codebase is a puzzle you have to painfully work out how to use.
I assumed there was some validity to the story just because of the sparseness of communication in the codebase. Good to know it’s not seen that way though. I am encouraging GSOC students to explain their features, inline in code, in the docs and here on the forums. I think the general stability and maintainability of the platform could do with more focus on communication and clarity more than rushing out solutions without either.
2 Likes