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 am currently working on an uni assignment. We have to write Javadoc comments. My problem is that I don't really know to whom I'm "talking" here.
Some examples for comments to different methods in my project:
"The next thing we care about is the number of..."
"We want to remove those items from the list because..."
So the questions is: can i put Javadocs like that or do I have to write them in formal language? And who do I adress in my sentences (if I can adress someone).
It's entirely up to you / your team how formal or informal to make your Javadoc.
It's relatively rare to directly address anyone (either with "you" or "we"), but again, it's your call. Consider the JDK's docs, which typically go something like this:
The String class represents character strings. All string literals in Java programs, such as "abc", are implemented as instances of this class.
Direct, clear, and impersonal. Just state the facts.
Another example (from Object#equals):
Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.
Notice how it didn't say "Note that you must generally override..." It doesn't tell anyone what to do, just notes that if doing X, generally it's necessary to do Y.
Javadocs matter most if you're publishing to third parties. You won't be present to expound on your code. Third parties will want to just use your classes wo/ worrying about how they fulfill their contract. Your documentation should tell them what they need to know: what the terms of the contract is. They need to know what to provide, what to expect back, exceptions, invariants, etc.
I would say keep the language formal in that case. It reflects better on you.
You don't communicate with third parties the same way you do your friends. Better to keep it formal.
I would stop using "we" and think more in terms of "you". It's about the consumer of your library, not the developers.
Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
Currently my program is filled with many ugly references that often make field or method access look like this: weakReference1.get().weakReference2.get().field1.getSomeCustomObject().field2. I want to move to shorter and faster strong references like field1.field2. But my program design is such that I will also have to go for an ArrayList element-by-element search (in a for-loop) instead of accessing a WeakHashMap by get() method.
Thus, I'd like to understand, can moving to simpler references compensate for rejecting HashMap performance wise. Herewith I presume that WeakHashMap.get() is much faster than a loop-search of ArrayList.
Can someone, please, give me a rough estimate? Or maybe there's even an appropriate comparison table like this one. I'd appreciate that.
Thank you.
Currently my program is filled with many ugly references that often make field or method access look like this:
weakReference1.get().weakReference2.get().field1.getSomeCustomObject().field2
Given that the objects involved are not Data Transfer Objects
this is a violation of the law of Demeter aka Don't talk to Strangers / Tell, don't ask!
Following this LoD principle you should move the operations working with the data in field2 to a new method in the class SomeCustomObject.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 6 years ago.
Improve this question
Most of the people says that abstraction is hiding something and showing only functionality to the user. Can anyone explain me what are all the things you are hiding and what are all the things you are showing?? please don't explain with the examples of animal, engine, vehicle.
I think this is a case where a concrete example would help a lot.
HashMap has an internal structure for handling hash collisions, which is an implementation of a singly-linked list. Now, do you know how that internal structure works, what it's called, what its fields are called, etc? More importantly, do you care, so long as the HashMap "just works"?
If the answer to both of those is "no" — which is what it should be for anything other than curiosity/learning purposes — then those details have been hidden from you and exposed via the abstraction of Map's interface.
The result is a class that's easier for you to reason about (because you have less to learn), and easier for the library maintainers to maintain (because they don't need to worry about a change they make breaking your code, so long as they still abide by the interface).
Abstraction is an overloaded term.
Abstraction, in object oriented languages, basically means leaving away unnecessary details when modeling real world objects. You could also think of it as a simplifying process.
Abstraction, in computer science as a whole, also means hiding complexity by providing some sort of simpler interface. Your question seems to aim at "data abstraction" which means hiding the exact way data is represented with an abstraction layer. This could be e.g. the Number data type in databases. You just know it is a number, but not how it is stored on disk.
Abstraction sometimes is used equivalently to encapsulation, too.
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
Lots of times I see people naming their methods a(), b(), c(), etc. instead of giving them names that describe what the method actually does. What is the point of this?
My guess is that you were reading obfuscated code.
Here's a nice article.
They shouldn't be doing this. It's bad practice.
Either the developer is being lazy, or they are showing a very simple example(still bad practice).
EDIT: (Given the extra detail in your comments)
In that case this is probably done by some automated program. The code the developer is actually working on wouldn't be using these names.
To minimize the load time for .js files, many developers will "compress" them. Compressing also has an option to obfuscate the code, making it more difficult to steal and change by making it difficult to understand. This happens just as you describe, by changing the variable names and function names to "a", "b", "c", etc. This has the side-effect of making the code smaller, since the names are now shorter. An example of a web tool that does this for you is here: http://www.developerfusion.com/tools/compressjavascript/
The code base that you maintain is certainly NOT the one that has been compressed and/or obfuscated.
Nothing. They are just too lazy to follow the standard naming conventions maybe because they are simply doing some quick POC(proof of concept) and they don't want to waste their time in typing some meaningful method name.
But one must always follow the naming conventions in their actual projects where others might be looking/maintaining their code.
This has always been discouraged by every community into programming and probably is a sign of a bad developer.
For more information on why and how do we use coding conventions see this
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'm new to Java, and get really confused about deep copy.
I think each method that takes some mutable objects as arguments and returns an object that is related to the input should make defensive copy. However, after some coding I find this is very tricky.
For example, I want to choose some objects from a container satisfying some conditions, and returns them as a smaller container:
List<SomeType> chooseWithSomeCondition(List<SomeType> input)
But SomeType is defined by others, which is not immutable, not clonable, not serializable, neither has any copy constructor. Since Java's final cannot help either, I don't know how to make deep copy here.
Is my criteria too strict? Is the code I've read problematic? Are there some other ways to make deep copy? Please share your thoughts, and thanks in advance.
In this particular case, the code is problematic, and I'd just do a shallow copy. In your docs, note that the method is actually "chooseWithSomeConditionAtThisInstant" and tell others NOT to modify the elements of either list, or to do so with care and thought. (There are use cases where you want changes to come through.)
In the case of a type where you cannot use normal copying methods for deep copy (in your case of non-serializable, non-clonable, non-instantiable...), you would need to work around with reflection.
If you think reflection is too slow, or constructors can't be used, then you may want to think about using sun.misc.Unsafe to instantiate.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 9 years ago.
Improve this question
i have been reading about this topic , and the more i read the more confused i get ,
can somebody please elaborate , we were using language C which follows structural approach ,
so what was wrong with this approach , that we moved to create a object oriented language JAVA .
I have been reading so many theoretical aspects , can some body please give more of a few practical illustrations ,
WHY WE NEEDED OBJECT ORIENTED APPROACH IN THE FIRST PLACE
I am not looking for an answer to be given in any interview or tutorial
I am looking for an answer to get the better understanding/practical importance of object oriented aproach
There are many explanations regarding this. But I would like to refer this
Modularity: The source code for a class can be written and maintained independently of the source code for other classes. Once
created, an object can be easily passed around inside the system.
Information-hiding: By interacting only with an object's methods, the details of its internal implementation remain hidden from
the outside world.
Code re-use: If a class already exists, you can use objects from that class in your program. This allows programmers to
implement/test/debug complex, task-specific objects, which you can
then use in your own code.
Easy Debugging: If a particular object turns out to be a problem, you can simply remove it from your application and plug in a
different object as its replacement. This is analogous to fixing
mechanical problems in the real world. If a bolt breaks, you replace
it, not the entire machine.