Comments missing

[nicola883]

Hi.
It seems that there are no comments in all the code in GitHub. Is there a reason for that? Is there a way to have them?

Thank you.

[emillod]

For what you need these comments?

[yuri]

Personally I don't need comments in most cases. For me it's easier to read code. If methods and variables are named properly, methods are short, it's not a problem at all.

If I had commended all my code it would have take 2x time longer to write EspoCRM. I'm not exaggerating.

If you are talking about documentation commenting, in most cases those are just a duplication of method names (the same text but with white spaces). PHP supports argument type and return type hinting, no need to copy the same information to comments anymore. It's my personal view.

There are situations where comments are needed though.

[nicola883]

Thank you for your answers.
Comments can help to use methods without the need to read the code. Also, they can be useful when you code. Often, I write comments before implementing the method: coding it is just a matter of realizing what the comment wants.
Moreover, in the first approach with a big project such as espocrm, it could make more accessible the engagement of new collaborators.
However, I agree with yurikuzn: names of methods, classes, variables are very well defined in espo that they could substitute the comments.

[tothewine]

There are situations where comments are needed though.

I believe doc blocks should be added to code that is not trivial or when it is not possible to detect the type of some variables. For example all those methods that use string manipulation/reflections to create method names. It is also important to document parameters and what they do: if a function accepts parameters in the $params argument they should be declared in a doc block. But since the current dependency injection system is a type-hinting hell those documentation blocks would probably never show in a ide anyway.

[yuri]

Dependency injection approach will be totally rewritten in 6.0. A lot of classes will be changed. Backward compatibility will be ensured as much as possible. Then I plan to start documenting API. The main parts for the beginning.