Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 8 years ago.
Improve this question
I like properly documented code and it is no-brainer for me to have properly documented public methods describing the contract and same applies for private or package internal methods to explain the code internals / implementation.
However I am not sure if I should in non-public and non-protected methods:
adhere to all the formalities as are description of parameters, return value and exception
if I should document self-explanatory private methods like fireSomeEvent where is obvious what it does at first sight as this only clutters the code
What is a standard approach to this?
Yes.
If anyone is ever going to look at your code, document. It's worth the extra line or two. Your code will appear more consistant and clear. If anyone else ever will look at your code you should definately comment.
Even people using code look at the source code of the code, even if it is documented. This helps the client better understand the library. By adding documentation, you make your code a lot easier to understand for clients too.
I personally document anything that might cause ambiguity later. I wouldn't document
def next = counter.incrementAndGet()
as its self explanatory. Anyone who thinks you should document methods like that has too much time on their hands.
Also, in private methods, I wouldn't personally worry about adhering to Javadoc standards. Just by writing some comments you're in my good books. I don't need #param or #return. Those are for public APIs.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
Let's say you have some issue to develop. And as recommended practice it is good idea to use interfaces ( I don't mean GUI, I mean interface or abstract class ). And you can apply two ( I'm pretty sure, but for now I noticed I apply two ) ways:
Design interfaces upfront and then implement them.
Implement classes and then on basics of classes discover interface.
Personally I prefer second option, but during discussions with other developers I noticed that somebody prefers first approach. I can say that I prefer second approach for the following reasons:
I can faster write code
I avoid unnesessary code ( something that I never will use )
Interfaces in that case are more binded to "real" life
For me it is more convenient.
I'd like to hear other advices why somebody prefers option 1 or option 2.
As usually I code in C#, but AFAIK java also have idea of interfaces
Closed. This question needs details or clarity. It is not currently accepting answers.
Want to improve this question? Add details and clarify the problem by editing this post.
Closed 8 years ago.
Improve this question
Please explain me the differences over time and space complexities in java for user defined and predefined functions in java. examples like, linked list, list, stack class. please explain this with valid example.
thank you.
There is nothing special in predefined function over user defined. The only thing is predefined has been written by somebody else for you. It depends on algorithm.
Crap code/implementation runs in a crap way. Doesn't matter if its user created or system/API provided. example at a high level is EJBs vs Spring.
Good written code runs pretty and sleek. Again doesn't matter who the hell wrote it.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I know that for methods, a explanation is provided and the #param, #return, and #throw. But for classes, are there any particular things that need to be included besides the explanation of the class?
At the class level, the documentation should explain:
Why/when would I want to use this class?
How do I use this class (examples)
How does this class play with other classes?
What is unexpected/special about this class? (thread safety, global variables, ...)
All in all, the class documentation should give a broader view, showing how the class fits into the rest of the code.
The tendency is to not include these comments or keep them very brief and let naming conventions drive our understanding of what the class should do. For example, a plain-old Java object (POJO) named "Address" might need very little in the way of documentation, other than what makes it truly unique. Take a look through recent Java projects on GitHub and you'll see this to be the case. Annotations and package names also help describe the class inherently.
If you focus more on naming, you shouldn't need to document much - other than what makes the class unique or limitations it may have.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
(This might be the wrong place to ask the question, please let me know).
Should I name my method isStaticallyImported or isStaticlyImported?
(They'd be pronounced pretty much the same way, I believe)
Of course they should be in good english. Even if the human brain will likely have no problems reading garbled up words, compilers do not enjoy the same luxury.
How many times have you miswritten a variable name, then later on used the correct spelling, only to find out that the program crashed at run/compile time?
This problem is only amplified when working on code that was not written by you, because we think of things as, well, things, and having to specially remember that the thing had to be spelled in a special way is just an unneeded break to your workflow.
Yes, your variables should be clear to the developer. You can name it whatever you want and it will work because the compiler doesn't care. When you name the variable in a human readable manner then developers after you will be able to read and understand your code much easier. You should name it "isStaticallyImported".
They should be in the most easily understandable language for those using and maintaining it in my opinion.
I'm also pretty sure the compiler doesn't care about the quality of spelling.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
This is kind of unusual question for developers but for some reason i want to post it here and hope to get adequate answer.
Here is a simple example:
I wrote a java function that calculates distance between two geo points. The function is not more than 50 lines of code. I decided to download a source code from ibm that does the same thing but when i opened it i saw that it looks very complicated and is almost thousand lines of code.
What kind of people write such source code? Are they just very good programmers? Should i use their source code or my own?
I have noticed this kind of thing lots of times and i from time to time i start to wonder if it is just me who do not know how exactly to program or maybe i am wrong?
Do you guys have the same kind of feeling when you browse throught some other peoples source code?
The code you found, does it do the exact same calculation? Perhaps it takes into account some edge cases you didn't think of, or uses an algorithm that has better numerical stability, lower asymptotic complexity, or is written to take advantage of branch prediction or CPU caches. Or it could be just over-engineered.
Remember the saying: "For every complex problem there is a solution that is simple, elegant, and wrong." If you are dealing with numerical software, even the most basic problems like adding a bunch of numbers can turn out to be surprisingly complex.