How to describe a class is my question? When you start a class in bluej there's always a documentation comment for the description of the class. What is to be written in that description?
For example I have a class called Economy that extends an abstract class Structure and the abstract class Structure implements an interface Basic. So what should I write in the description of the class Economy?
The very first thing to understand is ... one should actually write as few comments as possible. Instead: write code that can be read and understood and used without having (a lot) of additional comments around them.
Example: the names you choose "Structure" and "Basic" are very much ... meaningless. Those names do not tell anything about the intended behavior that one can expect from the corresponding class and the interface.
Thing is: comments lie. They add an extra quality to your source code; but a quality that can't be checked automatically. Thus it is very easy for that information to get out of sync with the things the code really does.
In other words: it can be perfectly OK to put an empty or very short description on a class. Besides: there is SRP that gives you guidance on "putting only a single responsibility" into each class. So, the core point of a "class description" would be to name/describe that one responsibility of the corresponding class.
Think about what someone would need to know if they wanted to use your class, or a basic description of the class you would give to someone if they didn't know what it did. Why would someone use your class? What does it do?
#Jägermeister mentioned how fallible code comments can be, so make sure that whatever you write, you keep it updated with what your code does. If you change the class, make sure you change your description of the class as well. And keep your description fairly short, you should most likely only need a few lines or less.
If you find yourself writing several lines of description, it might be a good idea to look at your class, and ask yourself if it's trying to do too much. In this case, it might be a good idea to make another class to accept some of its responsibilities.
Related
In an Android app. I have a requirement where I have my HomeActivity(Having 18000 lines of code) and if my device supports ARCore, I want HomeActivity to extend with ARBaseACtivity and if device doesn't supports ARCore then i need it to extend with NonARBaseActivity.
I am checking this condition in splash screen.
Now, there is a way that first comes is that i make two activities ,same a copy of HomeActivity but i need to know is there any better way to do that. Because i don't want to copy every time i do any change in one of the HomeActivity.
Downvoters please comment below so that i can improve where i am wrong . Thanks!!
The technical answer is: not possible.
In Java, your inheritance structure is fixed. It is simply not possible to have one class C extend class A in one context, and class B in another context. When you want to do that, you would end up having two classes, C1 and C2.
The real answer of course is: you have to step back and clearly architect your whole solution. Alone the 18K lines in one whatever is an indication that something is seriously wrong here. One could mention the good old FCoI principle, but then: 18K lines of code means a lot of code and features. It is simply impossible to give you proper guidance in a single answer on stackoverflow.
So, opinionated: you should step back, and identify some (architecture) experts to talk to. Then sit down with them (probably for hours, even days), and look at what you have got, and where you want to get to. Then work together on path there. Anything else is nothing but putting band-aids on symptoms. Sure, nothing will break when you don't do that. But each step forward will simply add mess to mess, making each step more expensive. Sooner or later, changing your monolith will become close to impossible, and everybody will ask to "throw it away, and start from scratch".
As complement to the excellent answer of GhostCat, I will give you a very important hint in OOP : to enhance at runtime the behavior of an object, the decorator pattern is often a way to consider.
Here HomeActivity appears as the element to decorate and ARBaseACtivity and NonARBaseActivity appears as decorator for that.
You should define a MyActivity interface that is the base class for both decorated and decorator objects.
So things are not simple because you will have to refactor many code lines but it will make your design more flexible and with classes that have consistent responsibilities instead of having a god object as activity !
Finally in the splash screen you could define a method that returns an activity decorating the HomeActivity according to the client material detected :
public MyActivity computeHomeActivity(){
HomeActivity activity = new HomeActivity();
if (isSupportARCore()){
return new ARBaseACtivity(activity);
}
return new NonARBaseActivity(activity);
}
I'm working on a moderate-sized Java project and trying to stick to the best possible practices, so I thought I'd run a few questions by you guys. Since I currently have time, I want to do it right. My apologies in advance if this sort of question isn't appropriate for StackOverflow. Perhaps others can refer to it for stylistic advice.
I'm writing a class called LinkOpener which has one public, static method: openAgencyWindows. You feed it an (oil) well serial number and, based on the serial number, a opens regulatory website for any one of the 50 US states. I'd be doing quite a bit of scraping, and due to the labyrinthine nature of these websites the code can get pretty extensive. Should I:
Include all of my scraping code in a LinkOpener class, including methods to handle serial numbers that correspond to each state in the US (sorted alphabetically).
Give each state its own class, which would extend a Scraper class that contains a few common website scraping/regex methods. Each state class would have one to three methods to assist with scraping.
Do something else?
Any assistance would be much appreciated.
Your second alternative will be more readable and a more object-oriented approach, which is good. It is also possible to call methods in the specific classes without knowing what state it is through abstract methods in the implemented class.
since you guys helped me out, I stumbled upon a strange 'issue' while programming Java.
I'm programming in the Play framework. It uses a lot of equally named classes among a number of packages. It makes your code look pretty, but I encountered a rather nasty side-effect:
I have a class 'User' in my controller package. But of course, 'User' is also a model.
While I'm writing in another controller, I need to create a new User object.
User u = User.find(...);
Because the controller User hasn't got such a method, this fails.
Am I correct if the only way to solve this is to write
models.users.User u = models.users.User.find(...);
After a little discussion with a Scala enthusiast, it seems that Java has no support to fix this kind of issues. Or is he wrong?
Kind regards
If I understand your question correct, if you do:
import models.users.User;
you will have access to the object without the full package. That's assuming you don't need the controller and the model in the same class.
If you need both, then yes, you have to fully qualify (add the package) one of them.
That said, it's a good convention to name all controllers XXXXController (or something like that). More generally, your own code should not have 2 different classes with the same name. The reason is that makes code readability lower, as User in one place behaves in a way and in some other piece of code behaves in a different way.
So the best solution would be to rename your controller.
He is right. You don't have any other way out of this.
It makes your code look pretty
I wouldn't say that. It makes my code convoluted and insanely difficult to comprehend.
You are correct. If you need to use both the User in your controller and the User class in the framework in the same class, then you can import one and then use the full package name for the other.
This can get confusing of course and I would reccomend one of two things:
1) one rename your class to something else.
2) do not import either and use the full package name for both. That way when reading the code it is less confusing.
I reccomend option 1.
I've been working on a fairly simple project for a class. I knew it was supposed to be written in Java, and I read enough of the Assignment description to have an idea what I was supposed to be doing, so I set about creating a nice, object-oriented solution ('cause it's Java, right?). When I finally get to reading the nitty-gritty details of the assignment, I come upon this little gem: The whole thing is supposed to be submitted as a single class file. It's too late to rewrite the whole thing now, so I tried to work around it by making all my classes static inner classes of the primary class. To my chagrin, I discovered that eclipse, at least by default, compiles the inner classes to separate class files still. I unfortunately don't know much about Java compiler settings, but I'm hoping theres a way to get them all compiled to one .class file. Is is it possible, or must I simply turn in what I've got with a note and take whatever my TA decides to dock me for it?
I'm afraid there is no such option. Each class is defined in its own class file. Even anonymous classes are defined in ParentClass$1.class
What I would suggest is to put a huge comment/documentation on why you think it is not good to put everything in one class. Of course it depends on the person "on the other end".
If one file, rather than one class is required, simply make a jar file.
If you are feeling brave you could create a jar for your application, encode it as a string in a your toplevelclass which extends a classloader and use this classloader to load the classes from the decoded jar file.
This is so crazy and shows so much knowledge of the Java platform it has to be worth extra credits.
As a TA, if a student send me a single java file, with an object-oriented design and nested classes, I would love it!
If the TA wanted the simplest solution to the problem and you over-engineered it, than it's of course another story.
Note that if the TA does not like nested classes and think they are bad, point him to NewSpeak and Gilad Bracha's posts. He's been involved in the Java Language Specification, he is an authority in the field and came up with a language entirely based on class nesting!
That said, should this be a single file, or single class file. If the former you can of course ZIP/JAR it, if the latter a little chat with the TA would be the way to go.
I am newbie to Java. I have some design questions.
Say I have a crawler application, that does the following:
1. Crawls a url and gets its content
2. Parses the contents
3. Displays the contents
How do you decide between implementing a function or a class?
-- Should the parser be a function of the crawler class, or should it be a class in itself, so it can be used by other applications as well?
-- If it should be a class, should it be protected or public class?
How do you decide between implementing a public or protected class?
-- If I had to create a class to generate stats from the parsed contents for eg, should that class be protected (so only the crawler class can access it) or should it be public?
Thanks
Ron
I think Andy's answer is very good. I have a few additions:
If you believe that a class will be extended in the future, you can set all your private methods (if any) to protected. In this way, any future extending classes can also access these.
I like the rule that a method shouldn't be longer than that you can see its opening and closing brackets ({ }) without scrolling. If a method is longer than that, try to split it up into several methods (private, protected or public by your preference). This makes code more readable, and could also save on lines of code.
So let's say a method is getting big and you split it up into several private methods. If these new methods are only used within the first "mother"-method, it makes sense to move all of that into a class of its own. In this way you will make the original class smaller and more readable. In addition, you will make the functionality of the new class easier to understand, as it is not mixed up with that of the original class.
The best guidance I've seen for these types of questions is the "SOLID Principles of OO Design."
http://butunclebob.com/ArticleS.UncleBob.PrinciplesOfOod
The most basic of these principles, and the one that sort of answers your first question is the "Single Responsibility Principle." This states that, "a class should have one, and only one, reason to change." In other words, your classes should each do exactly one thing. If you end up needing to change how that one thing works, you only have one class to change, and hopefully just one place to make the change within that class. In your case, you would probably want a class to retrieve the content from the URL, another class to parse it into some sort of in-memory data structure, another class to process the data (if needed), and yet another class (or classes) to display the content in whatever format you need. Obviously, you can get carried away with classes, but it's typically easier to test a lot of small, single-operation classes, as opposed to one or two large, all-encompassing classes.
The question on public vs. protected depends on how you plan to use this code. If your class could be used independently outside your library, you could think about making it public, but if it accomplishes some task which is specific or tied to your other classes, it could probably be protected. For example, a class to retrieve content from a URL is a good general-purpose class, so you could make it public, but a class that does some specific type of manipulation of data might not be useful outside your library, so it can be protected. Overall, it's not always black and white, but ultimately, it's usually not a huge deal either way.
I like to think of classes as "guys" who can do specific stuff "methods".
In your case, theres a guy who can fetch the content of an url if you tell him which url that is.
Then there is this another guy, that is really good at parsing content. I think he does that with a tool called rome, but i'm not sure. he keeps that private (hint ;) )
Then we have that third guy, who displays stuff. He's a bit retarded and only understands stuff that "another guy" produces, but hey thats fine.
Finally the project needs a boss guy, who gives orders to the other 3 guys and passes messages between them.
ps: I never really though about making classes protected or not. Usually they are simply public without any specific reason. As long as it don't hurt, why bother?