As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 9 years ago.
The community reviewed whether to reopen this question 11 months ago and left it closed:
Original close reason(s) were not resolved
I am a Java developer, and I'm interested in improving the quality of my Javadoc comments in the code and programs I write to make it more comprehensible and easier for other developers to implement.
I've read lots of articles, including those from official sources, and I try to follow the guidelines stated in the book
"The Elements of Java Style", but despite this, and after searching extensively online, I can't seem to find a practical way to compare my existing Javadoc(s) to model examples and maintain best practices for Java API documentation.
Peer review.
Try and find someone outside your team (a customer) and ask them what they think about your JavaDoc.
The customer is always right.
Also i can share you some stuff below
A great read on writing javadoc is at the sun site at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
The best thing I've learned from that text is probably that your class level javadoc should start with "Provides". This forces you to think about what that class provides to your program (or the world). It's not uncommon for me to redesign software because writing javadoc made me think "hey, this is not needed here!".
Other practical tips: When a getter is interesting, try to write it in the #returns tag. Not doing so might mean that you type stuff twice, once in the javadoc, and once after the #return tag.
An the best tip: If you don't know what to write, DONT. the Javadoc parser does a great job of automatically generating getter javadoc for example, but it only does it when you didn't add a /** */.
Javadoc should desccribe WHAT your method does, not HOW.
Javadoc is not your todolist. I've tried it, but for larger projects, it simply doesn't work.
In addition to the Sun's (now Oracle) documentation at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html I would recommend the "Item 44: Write doc сomments for all exposed API elements" from the "Effective Java" book by Joshua Bloch, 2nd ed. pp.203-208. This is a 6 page recommendation/tips with several practical examples.
You can use #link parameter for 'VoucherStore'
Example:
#return {#link VoucherStore} type Concrete Object based on storeType parameter
instead of
#return returns VoucherStore type Concrete Object based on storeType parameter.
Related
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
Edit:
Once again, thanks to those who commented and answered. Agreed, not the best question in the world, but I needed a little push to get past this obstacle in my mind. What I have taken with me in particular is that the return type is an important part of the method signature.
One of the important aspects of clean coding is picking good names for your classes, variables and methods.
Following what I have read in literature and online, I would try and pick names that are, firstly, as descriptive (and therefore unambiguous) as possible, and secondly, as concise as possible.
I am for my own amusement and learning writing a chess game in java, and I have stumbled upon a method that I simply can't figure out how to name in a satisfactory way. The method lives on my ISquare interface and is intended to bring me back a list of pieces that are currently attacking that square.
To be fully descriptive the name should indicate that the method returns a collection of pieces, arguably even a list, and that the pieces are attacking this square instance. One could argue that the latter is implied by where the method lives, but I'm not too sure about that.
The most descriptive name I can think of is probably in violation of every single other naming convention, and obviously won't do:
List<IPiece> giveMeTheListOfPiecesThatThisSquareIsUnderAttackBy();
These two alternatives show that the method relates to the current instance, but seem to hint that the result is of a boolean nature:
List<IPiece> isUnderAttackByPieces();
List<IPiece> underAttackByPieces();
The next one is descriptive about the return type, but not explicit about what the pieces are attacking:
List<IPiece> getAttackingPieces();
This one might satisfy my criteria, but intuitively I would say that using the words "This" and "Square" doesn't look very good:
List<IPiece> piecesAttackingThisSquare();
Currently I have settled with underAttackByPieces(), but as described above that doesn't quite nail it.
Any help you can offer will be most appreciated!
I would settle with getAttackingPieces. Since it's a method of ISquare, I think it is clear enough what is under attack. You can be more explicit in the method's Javadoc comment.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
Here's a real life example I had experienced before, and this is something that makes me ponder and question this mystery.
Before: I have no idea how to instantiate a class dynamically just by using the name of the class.
After: I looked around in someone else's Java source code, being determined to look for something unrelated to the above, like how to do collision detection, and just accidentally came across a piece of code that answers correctly my question of how to instantiate a class dynamically.
The piece of code in question is this:
A a = (A) Class.forName("A").newInstance();
Where A is the name of a Java source file, A.java.
From here, I was not only intrigued about it, but also starting to wonder, how a Java programmer learn all of this if they were given only the Java language documentation.
How do they know where to look for in the documentation, if they are practicing Java language?
I know that novice Java programmers get some experiences from expert Java programmers, but where do the expert Java programmers learn all of this, if they at first don't know where to look for in the documentation?
Or do they just read from page 1 to the end of the documentation, and follow along closely as much as possible, and start from there? That would take a long time to finish, and it would be an impressive feat to do.
Usually you search google for the Java docs... that send you to the Oracle website that contains it. http://docs.oracle.com/javase/7/docs/api/
On some cases only the API is necessary, but when you need a full formed example you could search for code samples or snippets, or the problem you want to solve itself (i.e. "java instantiate class dinamically").
On the issue of the dynamic instantiation there are a lot of ClassLoader things that can be done but the most basic exemple is similar to the one you found... but there is a catch.
When you reference the A class on your code the jvm automatically loads it for you.
When you do
A a = (A)Class.forName("A").newInstance();
You will reference the A class you already have a grip of.
What you could do is create an interface that the classes you want to instantiate have to implement, like this:
String classPath = ...
AInterface a = (AInterface)Class.forName(classPath).newInstance();
And you use it from there.
But you have to remember to add the try-catch block, because the newInstance method will only know if the referenced class has a default constructor when it tries ti instantiate it at runtime, and if it doesn't have there will be an exception.
The same goes for a exception thrown by the contructor itself, it will be encapsulated and thrown back at you.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 11 years ago.
The community reviewed whether to reopen this question 1 year ago and left it closed:
Original close reason(s) were not resolved
Hi
I have an assignment to teach a team the subject of design principle. As a final exercise to this mini course, I thought to give them an exercise in design pattern, in Java.
My idea is to give them a code written badly, and they should refactor it using several design patterns. I didn't find anything similar to that in my search (both in the web and in stack overflow).
Any references to something similar to what I'm looking for?
Thanks
One of the best sites out there : http://www.industriallogic.com/xp/refactoring/catalog.html
They basically show you code, and then the re-factored code. Its not going to be one big hopping pile of crap, but you can take an aggregate a couple and aggregate them together to form some ugly code, and then do the same to show the solution.
You can check this book "Refactoring: Improving the Design of Existing Code" of Martin Fowler. It contains examples of "smell" coding and provide solution to refactor it.
This has alot of code filling the bill. The author, Joshua Kerievsky, is also the founder of Industrial Logic, which has (as Nix noted in his response) good material on this topic, drawn from and augmenting this book.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 12 years ago.
I know that is Collections.sort() method in Java but I think quicksort is worth to remember and try.
My work target is general Java: web, database access, integration, not game developer, scientific application or another one that depends on advanced algorithms.
Which algorithms should I learn to pass without stress Java developer interview?
Fizz Buzz
I usually don't care, if a developer knows the basic algorithms by heart. I do care, if he is capabale of understanding requirements and translating them in correct, testable and understandable pieces of code.
Ah, and I do care if he knows how to implement the most common design patterns. And he should know when and how to use collections, threads and - String#split - it's amazing how many "developers" don't know how to read and process a simple csv file.
Although I fully agree with Joachim comment, I would go for : collection selection. This is not an algorithm per se, but rather a good view of which collection is good for which purpose :
sorted content with constant lookup time ? TreeSet !
mapped data with memorization of insertion order ? LinkedHashMap !
using that, and some knowledge of design patterns behind collections, you will far too often reply to algorithms questions using the knuth answer (or the subtle variation : as long as Sun developpers implemented it correctly, I only have to choose wisely).
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I'm wondering what's a good online judge for just practicing algorithms. I'm currently not very good at writing algorithms, so probably something easy (and least frustrating) would be good.
I've tried the UVA online judge, but it took me about 20 tries to get the first example question right; There was absolutely no documentation on how to read input, etc. I've read about Topcoder, but I'm not really looking to compete, merely to practice.
Take a better look at topcoder. Yes, they have competitions, but you can still easily just "play" by yourself. You are given a goal and a time limit and you choose your language, and then you code it. You can view the source code of the best coders to improve yourself.
I have used topcoder for awhile and have never been in any competition. Check it out.
You may also want to check out Project Euler. Not a judge, but there are mathematical problems and solutions available for many languages.
Have a look at SPOJ
CodingBat might give you some good practice. It responds instantly with test results.
This is a year old by now, so my answer is for future stumblers.
The ACM-ICPC Live Archive has a lot of great problems, and in a lot of different areas. (Project Euler is also great, but the problems are all number-theoretic.) And hoop-jumping is normal with these things... last I checked, Facebook Puzzles requires you to email a zip file containing the code and an Ant buildfile, and they take a long time to get back to you.
I've only sent Java code to UVa, so I'll elaborate a little on the Java particulars for anyone else who's struggling. Your class must be called Main, and its entry point must be the main method. You read from System.in. If you're on a Unix-y platform, after compiling you can use
Java Main < input.txt
to test your program.
The presentation has to be exact. For example, if they say "outputs should be separated by a blank line," that does not mean, "follow each output with a blank line." Finally, don't be afraid to check out their forums.
Reference: http://online-judge.uva.es/board/viewtopic.php?t=7429
(In their sample code, they read the input byte-by-byte. Don't do that; use Scanner instead. It's also not necessary to have the main method create an instance of the class. You can go 100% static, and often the problems are small enough that OOP doesn't buy you anything.)