Feathers: Why feathers source code with a litter comment?

[hifizz]

Feathers is a great project. I like it so much.

But I have used NodeJS just half a year, and I dont know much of backend. When I read feathers doc, I feel upset. I cant understand it completely. So I turned to read the source code. And I feel upset more. Because the hole feathers project was divided into so many small project... More Than This, these small project use different tech and use babel to translate the code(I can understand this, team for this project is great). when I use these module in my project, I can`t understand the translated code, in the mean time，I found the source code in these project have litter comment! I feel bad for this.

AND I CANNOT UNDERSTAND IT # WHY ?

LITTLE COMMENT.

I hope the source code looks like these project:
Sails
Ghost
Google Map markerclusterer

Their code comment is great. I can read their code and understand it easily. They use JSDoc comment style.

I was just bullshitting...

Hope feathers better.

[marshallswain]

Hey, how about checking out our new documentation.

Here's a great new guide for beginners: https://docs.feathersjs.com/v/auk/guides/step-by-step/readme.html

Here are new API docs: https://docs.feathersjs.com/v/auk/api/application.html Check out the entire sidebar in the API section. Most of it's fresh in the last few weeks.

The new Chat guide isn't complete, yet, so you'll have to pardon us on that one. This has been a major undertaking to completely rewrite the docs.

We have chosen to not flood the source with comments. I personally prefer reading code in the code, and comments in the docs, but I can see how that would make it difficult for a beginner to read the code. I'm fairly confident that the new docs will be a good solution to the problem, though. ;)

[eddyystop]

Hi stack Fizz.

I don't look at code in the /lib folder from npm. I look at the pre-transpiled code in the /src folder on GitHub as its in ES6 and much easier to reason about. Its straightforward to relate the two. I will, for example, place console.log statements in /lib, but I use /src to know where to place them.

I originally used JSDoc throughout the common hooks. I even had ESLint linting the JSDoc statements. Frankly, I think JSDoc is obsolete, a holdover from 2010. It was required by Google's Closure Compiler for type checking. The JSDoc linter I mentioned above is not even being maintained anymore, the author saying he believes function signatures should be part of the code statements rather than comments, hence Flow and TypeScript.

You might also want to look at https://blog.goyello.com/2013/01/21/top-9-principles-clean-code/ . It does not mention comments at all.

It does mention:

• Bad code does too much – Clean code is focused
• Smaller is better
• It should have unit and acceptance tests
• Expressiveness of the code means that it has meaningful names. These names should express their intention. They should not mislead you.
  They should be distinctive. Expressiveness makes code document itself making the need for documentation less important.
• If you want to read more about the subject of self-documenting code I recommend you to go through http://wiki.c2.com/?SelfDocumentingCode .

I've had to take some deep dives into Sails code. I do not think it follows the above principles.

[hifizz]

@marshallswain Wow! The new documentation is what I need.

I appreciate it just focus in the clean code. And I think code should express itself, too.

What Confused me is that I cannot know the module's property and function directly.And what is the export module like actually . I can't know the param type directly, either. These were what hindered me.

Just reading the clean code to understand a complexity system, I don't think it's a good idea. Every module has it's own property & function. To get all the property & function meaning, It's not a easy thing.

I think clean code is beautiful. I like it.

So, clean code must have a rich documentation. It's difficult for beginner, otherwise.

[marshallswain]

So, clean code must have a rich documentation. It's difficult for beginner, otherwise.

Exactly. I completely agree. This has been our focus for the current release.

Ok. I'm going to close this, since the new docs are helping. Thanks!

[hifizz]

@eddyystop Hey!

I appreciate the idea of clean code & clear code structure.

I read the /lib & /src both. Code in /lib was translated. It`s hard for reading. So I read them in GitHub, or git clone in local. The main project required many other modules. I can't know about them directly. so I need to read the required module. Because the documentation is not clear too. I just want to know about the required module's property & function. If the documentation is clear, I think I don't need to read the source code for get information.

I like clean code too. Code is for reading & understanding. Rich documentation, clean code, ok.If not, comment is need.But in complexity system, I think comment is useful for many users.

I didn't used flow. I'll try it. I use JSDoc just for highlight comment & type info. Maybe there is another way.

thanks.

[lock[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue with a link to this issue for related bugs.