search

PileProject / drive

The drive project
Other
5 stars 4 forks source link

Missing comments/javadocs #24

Closed tiwanari closed 7 years ago

tiwanari commented 8 years ago

Please add comments/javadocs and then check files.

mandaiy commented 8 years ago

I believe that we should discuss the format, the graininess, and the targets of the comment in advance. e.g., I do not know whether I should start the comment with capital letters or not, I should comment on private methods or not.

tiwanari commented 8 years ago

Yeah, you are right. Actually, they are what I'm confusing in refactoring.

Let me show some suggestions here:

And, I want to discuss:

Let's start discussing here for others and please tell me your concerns about them.

mandaiy commented 8 years ago

how about starts javadocs with upper case? I think it is natural that they become multiple lines and capital letters are easy to read for the situation.

I agree this since they are 'docs'. I also believe we should write the docs as sentence.

the format of javadocs like @params, @returns, and so on.

Do we need @author and @version? I think they are not necessary because we cannot specify the author and version in our development style. In my humble opinion, the @exception tags are mandatory if throws. And the @param and @return are nice but I don't think they should always be noted, since sometimes they provide no information.

http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDJGIJB

tiwanari commented 8 years ago

I totally agree with you.

Let me sum up them:

Is there any concern?

mandaiy commented 8 years ago

There are no other concerns. Thank you :)

tiwanari commented 7 years ago

62 solved this.