I have seen member functions programed both inside of the class they belong to and outside of the class with a function prototype inside of the class. I have only ever programmed using the first method, but was wondering if it is better practice to use the other or just personal preference?
Assuming you mean C++, it is always better to define functions outside of the class, because if you put it inside the class, compiler may try to inline it, which is not always desirable:
Increase in code size (every object file that includes this header might end up with a copy of the function in their code).
Breaking binary compatibility when function definition changes.
Even with inline functions, it is usually better to put definitions outside the class to improve readability of class public interface, unless the function is a trivial accessor or some other one-liner.
For C++, putting method definitions in the header file means that everything that includes a given header must be recompiled when the header changes - even if it's just an implementation detail.
Moving definitions out of the header means that files which include the header will need to be recompiled only when the header itself changes (functions added/removed, or declarations changed). This can have a big impact on compile times for complex projects.
There's advantages to both techniques.
If you place only prototypes in the class definition, that makes it easier for someone who is using your class to see what methods are available. They aren't distracted by implementation details.
Putting the code directly in the class definition makes it simpler to use the class, you only have to #include a header. This is especially useful (necessary) with templated classes.
Presuming the language is C++:
The bottom line is that is personal preference. Inside the class is shorter overall and more direct, especially for the
int getFoo() const { return _foo; }
type of function.
Outside te class, can remove "clutter" from the class definition.
I have seen both in use...
Of course, non-inlined functions are always outside the class.
It is also common to mix both styles when defining a class. For simple methods consisting of 1 or 2 lines it is common and convenient to define the method body within the class definition. For more lengthy methods it is better to define these externally. You will have more readable class definitions without cluttering them up with the method body.
Hiding the implementation of a method is beneficial in that the user of the class will not be distracted by the actual implementation, or make assumptions about the implementation that might change at a later time.
I assume you are talking about C++.
Having a nice and clean interface is certainly a good idea. Having a separate implementation file helps to keep your interface clean.
It also reduces compilation time, especially if you are using an opaque pointer.
If you implement the function inside the class, you cannot #include the class in multiple .cpp files or the linker will complain about multiple definitions of the function.
Thus, usual practice is to have the class definition in a .h file and the members implementation in a .cpp file (usually with the same name).
Again, assiming C++, I usually restrict this to placeholders on virtual functions, e.g.
virtual int MyFunc() {} // Does nothing in base class, override if needed
Anything else, and Andrew Medico's point kicks in too easily and hurts compile times.
Related
I am pondering over a few different ways of writing utility classes/functions. By utility I mean a part of code being reused in many places in the project. For example a set of formatting functions for the date & time handling.
I've got Java background, where there was a tendency to write
class UtilsXyz {
public static doSth(){...};
public static doSthElse(){...};
}
which I find hard to unit test because of their static nature. The other way is to inject here and there utility classes without static members.
In Dart you can use both attitudes, but I find other techniques more idiomatic:
mixins
Widely used and recommended in many articles for utility functions. But I find their nature to be a solution to infamous diamond problem rather than utility classes. And they're not very readable. Although I can imagine more focused utility functions, which pertain only Widgets, or only Presenters, only UseCases etc. They seem to be natural then.
extension functions
It's somehow natural to write '2023-01-29'.formatNicely(), but I'd like to be able to mock utility function, and you cannot mock extension functions.
global functions
Last not least, so far I find them the most natural (in terms of idiomatic Dart) way of providing utilities. I can unit test them, they're widely accessible, and doesn't look weird like mixins. I can also import them with as keyword to give some input for a reader where currently used function actually come from.
Does anybody have some experience with the best practices for utilities and is willing to share them? Am I missing something?
To write utility functions in an idiomatic way for Dart, your options are either extension methods or global functions.
You can see that they have a linter rule quoting this problem:
AVOID defining a class that contains only static members.
Creating classes with the sole purpose of providing utility or otherwise static methods is discouraged. Dart allows functions to exist outside of classes for this very reason.
https://dart-lang.github.io/linter/lints/avoid_classes_with_only_static_members.html.
Extension methods.
but I'd like to unit test some utility functions, and you cannot test extension functions, because they're static.
I did not find any resource that points that the extension methods are static, neither in StackOverflow or the Dart extension documentation. Although extension can have static methods themselves. Also, there is an open issue about supporting static extension members.
So, I think extensions are testable as well.
To test extension methods you have 2 options:
Import the extension name and use the extension syntax inside the tests.
Write an equivalent global utility function test it instead and make the extension method call this global function (I do not recommend this because if someone changes the extension method, the test will not be able to caught).
EDIT: as jamesdlin mentioned, the extension themselves can be tested but they cannot be mocked since they need to be resolved in compile time.
Global functions.
To test global functions, just import and test it.
I think the global functions are pretty straightforward:
This is the most simple, idiomatic way to write utility functions, this does not trigger any "wtf" flag when someone reads your code (like mixins), even Dart beginners.
This also takes advantage of the Dart top-level functions feature.
That's why I prefer this approach for utility functions that are not attached to any other classes.
And, if you are writing a library/package, the annotation #visibleForTesting may fall helpful for you (This annotation is from https://pub.dev/packages/meta).
In C++ (at least as of a decade ago), there was speed advantage in defining the body of a class method in the header file, where the class is defined. No function call overhead was suffered because, in the compilation process, the invocation of such functions was replaced by the code in the body of the function. Subsquently, all source level optimizations (and all optimizations beyond source level) could be brought to bear.
Is there an analogous advantage to putting the body of class methods in the classdef file itself rather than in a separate m-file? I'm speaking specifically about the case where one defines a #myclass/myclass.m, with method m-files in the directory #myclass. The two options I'm considering is to have the code for the body of a method mymethod put into the classdef in #myclass/myclass.m versus being in a separate file #myclass/mymethod.m.
However, an very related auxiliary question would be how those two options compare with having everything defined in a myclass.m file, with no folder #myclass.
Please note that I have previously posted this to usenet
Summarizing the comments as the answer to this question: Using an #classFolder folder containing separate method m-files is faster than having a single m file containing the entireties of the function definitions in the classdef. This is the case even though OOP in general has sped up in 2015b.
I find this a happy answer because I see great value in separating the code implementation of a class's methods from the class definition itself. That's the whole idea of separating interface from implementation. I can look at the classdef and see only a map of the class rather than have those key information elements completely dispersed by the deluge of code that accompanies implementation.
It's just too bad that this doesn't work so well for weakly typed languages. What's listed in the classdef is just member names (properties or methods) with no specification of what class they are. So not as much information as in a strongly typed language. In fact, very little info about what the class, its properties, and its methods really are. Furthermore, there is nothing to ensure that the actual method implementation even complies with the argument list in the classdef. These kind of details helped prevent development errors in a strongly typed language, especially when one's body of classes get large.
I need to create a package which will be used by other developers.
What is the best way to implement static methods?
For static (class) methods I must expect 1st parameter $class, and method must be called as a class method:
My::Package->Sub1();
From the other hand I can write a "regular" package subroutine (no $class parameter expected) which will perfectly do the same, but needs to be called differently
My::Package::Sub1();
So, basically there is no difference from the business functionality perspective (at least I don't see it, except package name availability through the first parameter), but 2 different ways to implement and call. Kinda confusing.
Which way should I use and when? Is there some rule?
Also, should I check if method was called as I expected (static vs package)?
First, a functional point: If a 2nd Class is create that inherits from My::Package, Child::Class::Sub1() will be undefined, and if Sub1 is written as a non-OO subroutine, Child::Class->Sub1() will ignore the fact that it's being called from Child::Class.
As such, for the sake of the programmers using your module, you'll want to make all of the subroutines in a Package/Class respond to a consistent calling structure/methodology. Your module should either be a library of subroutines/functions or a class full of methods. If part of it is OO, make it all OO. It is possible to create subroutines to behave in a mixed mode, but this complicates the code unnecessarily, and seems to have gone out of fashion on CPAN.
Now if there is truly no reason to distinguish between My::Package->Sub1() and Child::Class->Sub1(), then you can feel free to ignore the implicit class name parameter you'll be passed. This doesn't mean you shouldn't expect that parameter or that you should encourage a non-OO call format in an OO Module.
If I have a function (say messUp that does not need to access any private variables of a class (say room), should I write the function inside the class like room.messUp() or outside of it like messUp(room)? It seems the second version reads better to me.
There's a tradeoff involved here. Using a member function lets you:
Override the implementation in derived classes, so that messing up a kitchen could involve trashing the cupboards even if no cupboards are available in a generic room.
Decide that you need to access private variables later on, without having to refactor all the code that uses the function.
Make the function part of an interface, so that a piece of code may require that its argument be mess-up-able.
Using an external function lets you:
Make that function generic, so that you may apply it to rooms, warehouses and oil rigs equally (if they provide the member functions required for messing up).
Keep the class signature small, so that creating mock versions for unit testing (or different implementations) becomes easier.
Change the class implementation without having to examine the code for that function.
There's no real way to have your cake and eat it too, so you have to make choices. A common OO decision is to make everything a method (unless clearly idiotic) and sacrifice the three latter points, but that doesn't mean you should do it in all situations.
Any behaviour of a class of objects should be written as an instance method.
So room.messUp() is the OO way to do this.
Whether messUp has to access any private members of the class or not, is irrelevant, the fact that it's a behaviour of the room, suggests that it's an instance method, as would be cleanUp or paint, etc...
Ignoring which language, I think my first question is if messUp is related to any other functions. If you have a group of related functions, I would tend to stick them in a class.
If they don't access any class variables then you can make them static. This way, they can be called without needing to create an instance of the class.
Beyond that, I would look to the language. In some languages, every function must be a method of some class.
In the end, I don't think it makes a big difference. OOP is simply a way to help organize your application's data and logic. If you embrace it, then you would choose room.messUp() over messUp(room).
i base myself on "C++ Coding Standards: 101 Rules, Guidelines, And Best Practices" by Sutter and Alexandrescu, and also Bob Martin's SOLID. I agree with them on this point of course ;-).
If the message/function doesnt interract so much with your class, you should make it a standard ordinary function taking your class object as argument.
You should not polute your class with behaviours that are not intimately related to it.
This is to repect the Single Responsibility Principle: Your class should remain simple, aiming at the most precise goal.
However, if you think your message/function is intimately related to your object guts, then you should include it as a member function of your class.
We seems to be abstracting a lot of logic way from web pages and creating "helper" classes. Sadly, these classes are all sounding the same, e.g
ADHelper, (Active Directory)
AuthenicationHelper,
SharePointHelper
Do other people have a large number of classes with this naming convention?
I would say that it qualifies as a code smell, but remember that a code smell doesn't necessarily spell trouble. It is something you should look into and then decide if it is okay.
Having said that I personally find that a name like that adds very little value and because it is so generic the type may easily become a bucket of non-related utility methods. I.e. a helper class may turn into a Large Class, which is one of the common code smells.
If possible I suggest finding a type name that more closely describes what the methods do. Of course this may prompt additional helper classes, but as long as their names are helpful I don't mind the numbers.
Some time ago I came across a class called XmlHelper during a code review. It had a number of methods that obviously all had to do with Xml. However, it wasn't clear from the type name what the methods had in common (aside from being Xml-related). It turned out that some of the methods were formatting Xml and others were parsing Xml. So IMO the class should have been split in two or more parts with more specific names.
As always, it depends on the context.
When you work with your own API I would definitely consider it a code smell, because FooHelper indicates that it operates on Foo, but the behavior would most likely belong directly on the Foo class.
However, when you work with existing APIs (such as types in the BCL), you can't change the implementation, so extension methods become one of the ways to address shortcomings in the original API. You could choose to names such classes FooHelper just as well as FooExtension. It's equally smelly (or not).
Depends on the actual content of the classes.
If a huge amount of actual business logic/business rules are in the helper classes, then I would say yes.
If the classes are really just helpers that can be used in other enterprise applications (re-use in the absolute sense of the word -- not copy then customize), then I would say the helpers aren't a code smell.
It is an interesting point, if a word becomes 'boilerplate' in names then its probably a bit whiffy - if not quite a real smell. Perhaps using a 'Helper' folder and then allowing it to appear in the namespace keeps its use without overusing the word?
Application.Helper.SharePoint
Application.Helper.Authentication
and so on
In many cases, I use classes ending with Helper for static classes containing extension methods. Doesn't seem smelly to me. You can't put them into a non-static class, and the class itself does not matter, so Helper is fine, I think. Users of such a class won't see the class name anyway.
The .NET Framework does this as well (for example in the LogicalTreeHelper class from WPF, which just has a few static (non-extension) methods).
Ask yourself if the code would be better if the code in your helper class would be refactored to "real" classes, i.e. objects that fit into your class hierarchy. Code has to be somewhere, and if you can't make out a class/object where it really belongs to, like simple helper functions (hence "Helper"), you should be fine.
I wouldn't say that it is a code smell. In ASP.NET MVC it is quite common.