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
Consider that I have a complex class structure where many elements inherit from other elements. I may have a method GetStuff(string stuffName, int count) defined in an interface, which is inherited by other interface, which is then implemented abstractly by an abstract class, which is then implement explicit in a concrete class etc. etc...
How should I handle inherited members such as GetStuff() when documenting my code with XML comments which will be used with a tool such as Doxygen or Sandcastle? It seems wrong to just copy and paste the same description at each level. Should I be considering a different audience at the interface level vs the concrete class level? For example the documentation for GetStuff() at the interface may consider people implementing the interface, whereas the documentation at the concrete level may instead consider people who will be using the class?
Document the interface method according to its code contract. Do not comment on its implementation, only on its semantic purpose, i.e. what it’s supposed to do, not how. The audience for this documentation is both your implementors and your users: the method will both be implemented as well as called.
Document the abstract method simply by saying that it implements the interface method and linking to it. There is nothing extra to be said about it, and duplicating the comment violates the DRY (Don’t Repeat Yourself) principle: you would have to remember to make any change to it in both places. (Of course, in the case of an abstract method that doesn’t implement an interface method, document it in the same way that you would document an interface method.)
Document the concrete implementation by saying that it implements the interface method and/or that it overrides the abstract member. Optionally add information about its implementation if it is relevant to the caller — for example, its performance characteristics, or situations in which it might throw, etc.
remark
on part of post
by Eric Anastas
It seems wrong to just copy and paste
the same description at each level.
I can imagine it being wrong to just copy. It is however possible to let doxygen copy it for you and then change what you would like to change for that implementation/scope.
For more information, you can look at the description for #copydoc.
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
Why do in most programming languages do you get the ability to have private and or public methods/functions classes and properties?
Does it make much of a difrence to let's say.. have all classes, methods and properties be public?
I know that if you have all your methods, classe ans properties set to private nothing will work.
So at least I know that much.
But does the distinction between the two matter? What's the big deal if one class knows another Class "that is meant to be private" exists?
When you make something public, you enter a contract with the user class: "Hey, this is, what I offer, use it or not." Changing the public interface is expensive, because you have to change all code using that public interface, too. Think of a developer of a framework like Cocoa used by thousands of developers. If you change one public methods, for example removing one, thousands of apps break. They have to be changed, too.
So making everything public simply means that you cannot change anything anymore. (You can, but the people will get angry at one point.)
Let's think of having a class implementing a list. There is a method to sort it: sortListWithKey. You make that public because you want the users of the class to get a sorted list. This is good.
There are several algorithms for sorting. Let's say, you implement one that needs to calculate the meridian (the middle element). You need this method internally for your sorting algorithm. So it is enough, to implement it privately. Changing the whole structure of data holding including the implemented sorting algorithm is no problem and will not break existing code using that class.
But if you made the meridian method public (remember: you implemented it, because you needed it internally), you still have to keep it, even the new sorting algorithm does not need it. You cannot remove it anymore, even with the new structure it is very hard (and/or expensive) to keep the method.
So make that part of your implementation public that is useful for the users, but no more. Otherwise you shackle yourself.
If humans had perfect memory, documentation and communication skills, and made no mistakes, then there might not be a useful difference. But using or changing something from the wrong file and then forgetting about it (or not documenting it clearly for the rest of the team, or yourself in the future) is too common a cause of hard-to-find bugs.
Marking things private makes it a bit more work to create the same types of bugs, and thus less likely that lazy/sleepy programmers will do all that extra work just to mess up the application.
In computer science it is called information hiding. You, as a programmer, want to offer only necessary methods or properties to other programmers which will use your public API and this is the way how you can achieve so-called low coupling between modules.
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 4 years ago.
Improve this question
After reading Interface vs Base class I understand that Inheritance should be used where there exists a "is-a" relationship and interfaces should be used in "can-do" kind of places.
If that means, base class can only have business objects and interfaces will have only the contracts?
For e.g Dog class will have a base class Animal with properties like Eye,Nose,Leg etc and interface IAnimal will have "Run", "Jump" etc.
Will design applicable for all the scenarios?
The answers on that question you linked actually say it all. Especially the accepted answer and its first comment. You use an interface to declare the contract and a base class for shared implementation.
I'd consider it a common practice to define interfaces for (almost) everything. An interface can also contain getters and setters and therefore define its subtypes properties. If two or more classes that implement that interface share some implementation, you can moved that to a base class. That base class would then also implement the interface.
Your understanding is correct, but I think it relies more on good practices than actual language rules. Please consider the following:
In languages that support multiple inheritance (C++) interfaces are just classes with all methods virtual and abstract. See this question
Languages that don't allow multiple inheritance (Java), the most important difference is that a class can have no more than 1 superclass, but can implement an arbitrary number of interfaces. There are also differences in declaring variables (variables are implicitly static and final in Java interfaces) but it's still not a big leap to think of interfaces as of 100% abstract classes.
Java 8 introduced default methods (see this question), which can kind of blur the obvious distinction between those two.
So while technically it's not true neither that interfaces must only define the contract (default methods can implement a fallback behavior in a Java 8 interface) nor that abstract classes must define behavior (because a pure abstract class with no implementations can exist), the approach that you described is kind of reasonable and common in real world.
It depends.....
That's a good starting point but it is not right to say that it will be applicable in all scenarios. Systems keep changing and as part of refactoring (http://refactoring.com/catalog/) sometimes interfaces become subclasses and the other way round. Interfaces are good for Mix-ins which you mention as "can-do" kind of behavior and Inheritance where a group of classes share certain properties and possibly some behavior enabling reuse and avoiding code duplication (which is essentially what a IS-A relationship is). You can read more about it in Effective Java by Joshua Bloch (there is an item on Interfaces and Inheritance).
If we take your example, the methods "Run" and "Jump" can be either defined in Animal base class or they can go in an interface as you mention, in fact they can actually go in multiple interfaces too. So you might start off by building a inheritance hierarchy and later refactor them into interfaces as the system evolves.
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
Say I have a class in a programming language:
class name {
variable_name = 1;
method_name(x) {
// return something
}
}
foo = new name();
print(foo.method_name(foo.variable_name));
How correct is the following? Can we make it more correct?
If I want to talk about a specific instance of a method (foo.method_name), would I say 'the method_name-method of the object foo'? Or something else? Or does talking about the instance of a variable of method make no sense?
If I want to talk about a general object of any name, and refer to its method_name-method or variable, what would I say? Would I say 'the method_name-method/variable_name-variable of the class name?' or something else?
Thank you for your time.
Kind regards,
Marius
Talking about a specific instance of a method doesn't really make any sense as you say. Usually we talk about instances of classes - objects - and their methods. Thus one would normally talk about something like "calling method_name on foo" or simply foo dot method_name.
That's a fine way of saying it. In my experience it doesn't really matter all that much in day to day communication as the method really does the same thing anyways, just with different values in it's scope. It's what it does that really matters (e.g. accelerate() or toString()). Perhaps the most important part when talking about methods, variables etc. is communicating clearly if they happen to be static - i.e. not belonging to any given instances. In day to day speak I wouldn't make any effort to differentiate very clearly between "then we can just call accelerate on our car instance" and "the car class has a method named accelerate" (it's given that this is a non-static method) - I might however specify that "our car class has a static method to help us calculate acceleration.
In a nutshell:
Classes: (which may be instantiated to objects)
can have -
(non-static / instance) members
- public
- methods
- properties
- private
- methods
- properties
(static / class) members
- public
- methods
- properties
- private
- methods
- properties
However, methods have/can also be called messages, selectors, or behaviours (depending on the language in question, and in particular contexts.) It's occasionally considered incorrect to call them functions, however no one in their right mind should take you to task over such things. (notably the appearance of the keyword function in ECMAScript shows its level of acceptability. As a rule of thumb, the language domain would always define correctness, otherwise generally the term is fine/understandable but can lead to ambiguity.) Similarly properties are variously called, fields, attributes or variables.
An alternative name for non-static methods or properties is to call them instance methods or properties. While static methods / properties may be referred to as class methods / properties. By the way, ommitting the non-static qualifier, is usual and implicit.
As a general guideline, refer to the language under use to determine the correct terms, as they are specific to the various language cultures.
The assumption in writing this, is that there's no need to outline the scope/access differences of these class members. If that's required, I'd be happy to add a note.
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 4 years ago.
Improve this question
What I have been taught, and therefor restricted to, is to pass an object as a handler. I have used this approach in both my Java and Objective-C programming projects, and it works.
However, I stumbled upon a framework that registers a class as the handler, not an object. I wish that framework was open-source so I can see how that works, but it isn't :/.
Beware! After I register the class, I implement non-static methods to handle the events. If they were static, it would be obvious how this works, and I would really hate this approach.
So, these are my questions:
How does a class handler work and differ from normal object handlers?
When would you recommend one over the other?
Does this pattern have a name?
What I mean by object handlers:
Java:
button.addActionListener(handlerObject);
What I mean by class handlers:
Java:
object.addCrazyHandler(MyHandler.class);
Java (not sure about Objective-C) allows you through the Reflection API to do introspection on objects and their classes, hence the Object.getClass() method and all the methods on Class. Not only can you find all the constructors, methods, fields, implemented interfaces and superclass of a class, you can also call them (though it's slower than a direct call): newInstance() on constructors, invoke() on methods, get() or set() on fields. For example (exception handlers omitted), to call a no-argument constructor through Reflection:
Object o = SomeClass.class.getConstructor().newInstance();
Lots of frameworks use this: test frameworks such as TestNG or JUnit use it to instanciate the test classes, for example. So does Spring when you use XML configuration.
In your case, I suppose the framework wants to control the lifecycle of the handler, which it can't if you provide it with an instance. Another option would have been for it to take an instance of a factory, but that may be too restrictive. That can also mean more boiler-plate code to write, when it can easily create the object itself.
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 6 years ago.
Improve this question
There are two classes:A and B.
And I need to implement a function whoViewed,
I have two options,make it an member function of A and B.Which smells a little duplicate.
Another choice is to make it a separate class:Viewer,but it's more abstract.
If you were me,which way will you choose?
To make it more general:
what will you do when you need to get statistic information across different classes(like get the latest viewed 10 entities{which can be A or B} from database) within the scope of OOP.
I would recommend not using inheritance and instead go with composition. Create a class called ViewMonitor which will handle the shared functionality. The odds are that there is no logical way to design an inheritance structure.
Obviously duplicating the whoViewed() method in 2 places is bad, so that option is off the table. You have a third option: Create a parent class that implements whoViewed() and have A and B inherit from it. The famous Gang of Four Design Patterns book recommends favoring composition over inheritance. So this would suggest making the Viewer class you mentioned in the question. Given the limited context provided in your question, I would suggest taking the GoF's advice and going with the Viewer class.
Incidentally, if you expect the implementation of whoViewed() to be different in A and B, you could make Viewer an interface and implement the interface in A and B.
if WhoViewed in A and B has the exact same functionality, make a class, from which they can inherit.
If the implementation of the method is different for both classes, of if they already inherit from another class, use an interface for A and B.
I would not suggest to introduce inheritance here, because it is serious decision, require that both classes to be truly polymorphic in all aspects.
In this case - make implementation in the third class, make this class a member of A and B, and then delegate call to the whoViewed method to this member.
In a pseudo code:
class C
{
WhoViewed();
}
Class A{
C m_C;
WhoVied{
m_c.WhoViwed();
}
In the B do the same as in A.
If speaking in OOD language - replace inheritance with delegation.
I would use composition and delegate to an external object. Your problem sounds like a cross cutting concern, hence AOP could be an option for you.
Depending on the language you could use Mixins (Ruby) or Traits (Scala).
This seems more like an AOP problem and should be solved using an aspect.
If you can think of the "who Viewed" as an aspect that you can then store the latest viewed 10 entities from database.
You would then intercept the calls to your entities and store the required metadata off in an easy to locate location.
if whoViewed() implementation is same for both then I would like to have a seperate helper class or an abstract class which is inherited by both A and B.
if whoviewed() implementation is ways apart write them in their respective classes.