search

ClanCats / Hydrahon

🐉 Fast & standalone PHP MySQL Query Builder library.
https://clancats.io/hydrahon/master/
MIT License
278 stars 58 forks source link

Unnecessary Comments #53

Closed DioxideHydrogen closed 3 years ago

DioxideHydrogen commented 3 years ago

So i was reading the Code Clean this times, and one topic that the book talk about is about unnecessary comments. I like so much of Hydrahon and i pretend contribute to its code. So in this weekend i've cloned the repo and decided to see if i can make the code a little cleaner.

What do you think about a PR removing this UNNECESSARY comments (Without be rude)? @mario-deluna

image

JLowborn commented 3 years ago

Refactoring the code is always a good idea, I often use Hydrahon myself when developing web applications, I would like to see how this'll turn out.

mario-deluna commented 3 years ago

Hi there, while I understand and agree that there are many comments with redundant information, I do not agree with removing them.

PHP, especially in the version we are trying to keep this libs version v1 compatible with, is not very explicit, so having Docblock information helps. Furthermore, maybe a bit of a controversial opinion, I believe it increases the readability of the code a lot.

Now my suggestion would be: instead of removing the comments, improve them. Replace the redundant information with a helpful explanation of why the method is there, its purpose, and how it should be used.

The Nice Side-effect is that we could use these functions to extend the semi-automatic documentation by parsing those Docsblocks.

DioxideHydrogen commented 3 years ago

Hi there, while I understand and agree that there are many comments with redundant information, I do not agree with removing them.

PHP, especially in the version we are trying to keep this libs version v1 compatible with, is not very explicit, so having Docblock information helps. Furthermore, maybe a bit of a controversial opinion, I believe it increases the readability of the code a lot.

Now my suggestion would be: instead of removing the comments, improve them. Replace the redundant information with a helpful explanation of why the method is there, its purpose, and how it should be used.

The Nice Side-effect is that we could use these functions to extend the semi-automatic documentation by parsing those Docsblocks.

That's Great. I miss the "Discussions" of Github here. So i'ved that open this issue.