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
The common sense tells that the Doxygen comment blocks have to be put in the header files where the classes, structs, enums, functions, declarations are. I agree that this is a sound argument for a libraries that are mean to be distributed without its source (only headers and libs with object code).
BUT...I've been thinking of the exact opposite approach when I'm developing an internal to the company (or as a side project for myself) library that will be used with its full source code. What I propose is to put the large comment blocks in the implementations files (HPP, INL, CPP, etc) in order NOT to clutter the inteface of the classes and functions declared in the header.
Pros:
Less clutter in the header files, only categorizing of the functions can be added.
The comment blocks that are previewed when Intellisense for example is used doesn't clash - this is a defect that I have observed when I have a comment block for a function in the .H file and have its inline definition in the same .H file but included from .INL file.
Cons:
(The obvious one) The comment blocks are not in the header files where the declarations are.
So, what do you think and possibly suggest?
I like to make use of the fact that names can be documented in multiple places.
In the header file, I write a brief description of the method, and document all its parameters - these are less likely to change than the implementation of the method itself, and if they do, then the function prototype needs to be changed in any case.
I put long-format documentation in the source files next to the actual implementation, so the details can be changed as the method evolves.
For example:
mymodule.h
/// #brief This method adds two integers.
/// #param a First integer to add.
/// #param b Second integer to add.
/// #return The sum of both parameters.
int add(int a, int b);
mymodule.cpp
/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// #TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
return b + a;
}
Put the documentation where people will read and write it as they are using and working on the code.
Class comments go in front of classes, method comments in front of methods.
That is the best way to make sure things are maintained. It also keeps your header files relatively lean and avoids the touching issue of people updating method docs causing headers to be dirty and triggering rebuilds. I have actually known people use that as an excuse for writing documentation later!
Having comments in the header means that all users of a class must be recompiled if a comment is changed. For a large projects, coders will be less inclined to update comments in headers if they risk spending the next 20min rebuilding everything.
And.. since you're supposed to read the html doc and not browse through the code for documentation, it's not a large problem that the comment blocks are more difficult to locate in the source files.
Headers:
Easier to read the comments since there is less other "noise" when looking at the files.
Source:
Then you have the actual functions available for reading while looking at the comments.
We just use all global functions commented in headers and local functions commented in source. If you want you can also include the copydoc command to insert the documentation in multiple places without having to write it several times ( better for maintenance )
You could however also get the results copied over to different file documentation with a simple command. E.g. :-
My file1.h
/**
* \brief Short about function
*
* More about function
*/
WORD my_fync1(BYTE*);
MY file1.c
/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}
Now you get the same documentation on both functions.
This gives you less noise in the code files at the same time you get the documentation written in one place presented in several places in the final output.
I'm using QtCreator for programming. A very useful trick consists in Ctrl-Clicking on a function or method to get the declaration in the header file.
When the method is commented in the header file, you can quickly find the information you are looking for. So for me, comments should be located in the header file!
Usually I put documentation for interface (\param, \return) in .h file and documentation for implementation (\details) in .c/.cpp/.m file. Doxygen groups everything in the function/method documentation.
I put everything in the header file.
I document everything, but only generally extract the public interface.
In c++ sometimes implementation can be split between header and .cpp modules. Here it seems cleaner to put it documentation into the header file as that is the only place that all public functions and methods are guaranteed.
Related
I prefer working with files that are less than 1000 lines long, so am thinking of breaking up some Erlang modules into more bite-sized pieces.
Is there a way of doing this without expanding the public API of my library?
What I mean is, any time there is a module, any user can do module:func_exported_from_the_module. The only way to really have something be private that I know of is to not export it from any module (and even then holes can be poked).
So if there is technically no way to accomplish what I'm looking for, is there a convention?
For example, there are no private methods in Python classes, but the convention is to use a leading _ in _my_private_method to mark it as private.
I accept that the answer may be, "no, you must have 4K LOC files."
The closest thing to a convention is to use edoc tags, like #private and #hidden.
From the docs:
#hidden
Marks the function so that it will not appear in the
documentation (even if "private" documentation is generated). Useful
for debug/test functions, etc. The content can be used as a comment;
it is ignored by EDoc.
#private
Marks the function as private (i.e., not part of the public
interface), so that it will not appear in the normal documentation.
(If "private" documentation is generated, the function will be
included.) Only useful for exported functions, e.g. entry points for
spawn. (Non-exported functions are always "private".) The content can
be used as a comment; it is ignored by EDoc.
Please note that this answer started as a comment to #legoscia's answer
Different visibilities for different methods is not currently supported.
The current convention, if you want to call it that way, is to have one (or several) 'facade' my_lib.erl module(s) that export the public API of your library/application. Calling any internal module of the library is playing with fire and should be avoided (call them at your own risk).
There are some very nice features in the BEAM VM that rely on being able to call exported functions from any module, such as
Callbacks (funs/anonymous funs), MFA, erlang:apply/3: The calling code does not need to know anything about the library, just that it's something that needs to be called
Behaviours such as gen_server need the previous point to work
Hot reloading: You can upgrade the bytecode of any module without stopping the VM. The code server inside the VM maintains at most two versions of the bytecode for any module, redirecting external calls (those with the Module:) to the most recent version and the internal calls to the current version. That's why you may see some ?MODULE: calls in long-running servers, to be able to upgrade the code
You'd be able to argue that these points'd be available with more fine-grained BEAM-oriented visibility levels, true. But I don't think it would solve anything that's not solved with the facade modules, and it'd complicate other parts of the VM/code a great deal.
Bonus
Something similar applies to records and opaque types, records only exist at compile time, and opaque types only at dialyzer time. Nothing stops you from accessing their internals anywhere, but you'll only find problems if you go that way:
You insert a new field in the record, suddenly, all your {record_name,...} = break
You use a library that returns an opaque_adt(), you know that it's a list and use like so. The library is upgraded to include the size of the list, so now opaque_adt() is a tuple() and chaos ensues
Only those functions that are specified in the -export attribute are visible to other modules i.e "public" functions. All other functions are private. If you have specified -compile(export_all) only then all functions in module are visible outside. It is not recommended to use -compile(export_all).
I don't know of any existing convention for Erlang, but why not adopt the Python convention? Let's say that "library-private" functions are prefixed with an underscore. You'll need to quote function names with single quotes for that to work:
-module(bar).
-export(['_my_private_function'/0]).
'_my_private_function'() ->
foo.
Then you can call it as:
> bar:'_my_private_function'().
foo
To me, that communicates clearly that I shouldn't be calling that function unless I know what I'm doing. (and probably not even then)
Do I really have to use the ClassImp macro to benefit the automatic dictionary and streamer generation in ROOT? Some online tutorials and examples mention it but I noticed that simply adding the ClassDef(MyClass, <ver>) macro to MyClass.h and processing it with rootcint/rootcling already generates most of such code.
I did look at Rtypes.h where these macros are defined but to follow preprocessor macros calling each other is not easy and so, it would be nice if experts could confirm the role of ClassImp. I am specifically interested in recent versions of ROOT >= 5.34
Here is the answer I got on roottalk mailing list confirming that the usage of ClassImp is essentially outdated.
ClassImp is used to register in the TClass the name of the source file
for the class. This was used in particular by THtml (which has now
been deprecated in favor of Doxygen). So unless you code/framework
needs to know the name of the source files, it is no longer necessary
to have ClassImp.
ClassDef is necessary for class inheriting from TObject (or from any
classes that has a ClassDef). In the other cases, it provide
accelerator that makes the I/O slightly faster (and thus is
technically not compulsory in this case). It also assign a version
number to the schema layout which simplifies writing schema evolution
rules (on the other hand, there is other alternative to assign a
version number to the schema layout).
What exactly are you trying to do? The ClassImp and ClassDef macros add members to the class that provide Run-Time Type Information and allow the class to be written to root files. If you are not interested in that, then don't bother with these macros.
I never use them.
Baby new to Xcode, Cocoa touch and iOS development in general. And am taking the Stanford walkthrough for their iPhone class. I am a little confused at a couple of places and need to shoot my doubts to you guys:
I have two classes that I have created for my model, essentially CalculatorBrain.m and CalculatorBrain.h.
From what I gather, in Objective C, creating a class essentially consists of two functions, one is to declare the class which contains the method/messages and other variables while the other is the actual implementation for the same. From this stems two questions:
Why must I declare a class without implementing it's methods at first? (the concept seems to be borrowed from interfaces) and only then move on to implementing it .
From the above question, as I go through the walkthrough, I notice that the class declaration took place in CalculatorBrain.h whereas the methods were actually implemented in CalculatorBrain.m. I am unable to grasp the nuances of why this was done so if anybody is willing to shed some light on this, it would really help
Thanks again,
Parijat Kalia!!!
These are traditions from the C world, and they're just common practice to avoid some problems. They aren't two classes, they are the definition (in the .h file) and the implementation (in the .c or .cc file).
If you defined the class in the .c file, you couldn't refer to it elsewhere because it wouldn't be defined. You could include your .c file, but then you'd have two copies of the code. You could also use the "extern" keyword, but at this point it's kind of odd.
If you put code in the .h file, then when it's included the code gets included. This means you can get compiler errors that you have three "getMyThing" functions.
This means you can give out your headers to others without giving away your top-secret implementation (useful for making libraries), include your header without worrying about the possible multiple definitions, etc. You can also add variables and functions in the .c file which people using the header (like your other code) can't see or use, so you don't have to worry about changing it later and having compilation break.
Using a static function, I can limit the linkage of my function to the file at hand and that is perfect in many cases. But I have a class that is unwieldy as one file, but breaking it up is made more frustrating because there are functions that I would like to keep 'private' but are needed throughout.
One part of the answer must be counter-questions, such as:
Why is your class so big that it must be split up?
Are you sure your class is so big that it must be split up? (How big is 'big'?)
Are you sure you have your class properly abstracted?
Can you make the common functions into a new class that can be used by the main class you are working with? That will hide the functions behind a class interface barrier.
On the whole, if you can avoid it, do not split the class file up arbitrarily because of size constraints; keep together that which belongs together.
A Gruesome Possibility
Assuming that a split is necessary and an orthodox split (into various classes that work together) is not possible, the question becomes: how gruesome will you accept your code being? (It's already a bit gruesome since there's an awful lot of functionality in a single file; can you stand it becoming more gruesome?)
Assume your class is in 4 (or more) files.
class.h
class.c
class1.c
class2.c
The header, class.h, is orthodox - self-contained and idempotent. It is used by the outside world (meaning outside this collection of source code) to access the facilities provided by the class.
The files class1.c and class2.c contain implementations of the functions in the class. They could be given a separate, distinctive file suffix - there might be some advantages to doing so. The files are not designed to be compiled standalone; they are strictly a convenience that splits the source up because the class got too big.
The file class.c is what you compile. It contains:
#include "class.h"
Other definitions needed by the class internals.
#include "class1.c"
#include "class2.c"
Thus, although the source is split up, you actually compile a single file, class.c.
In your makefile or equivalent, you specify that class.o depends on the header and all three source files; if any of those changes, then you need to recompile the whole lot. One advantage of changing the suffix of the implementation files (class1.c and class2.c) is that they will not compile separately because the suffix is not recognized by the C (Objective-C) compiler. One downside of changing the suffix is that your syntax-aware editor won't be aware of the correct syntax highlighting for the separate files unless you tell it the file type. If you use an IDE, it may also be less than amused at this trickery.
If you work on a machine where the size of the source means it cannot all be compiled at once like this, then you are snookered. This technique does not help at all; you have to split the files up and compile them separately. In that case, really look hard at whether you can split the code cleanly into several classes which can be managed in an orthodox way.
By request, my comment on the OP as an answer:
There's no language support for this that I'm aware of... You could put all the support functions in a separate c file and only #import its header from the class implementation files? If they don't have to be C functions (for passing as callbacks to C APIs, for example) I'd reimplement them as methods on the class and declare the private interface in a separate header—each implementation file would then #import both the "public" and "private" header.
Prefix their names with output of a cryptographic RNG. Now you don't have to worry about unintentional name collisions. Problem solved. You can hide the renaming in preprocessor macros if you really like.
What is the recommended way to define private and protected methods in Objective-C? One website suggested using categories in the implementation file for private methods, another suggested trailing underscores, or XX_ where XX is some project-specific code. What does Apple itself use?
And what about protected methods? One solution I read was to use categories in separate files, for example CLASS_protected.h and CLASS_protected.m but this seems like it could get very bloated. What should I do?
There are three issues:
Hiding from compiler.
That is, making it impossible for someone else to #import something and see your method declarations. For that, put your private API into a separate header file, mark that header's role as "Private" in Xcode, and then import it in your project where you need access to said private API.
Use a category or class extension to declare the additional methods.
Preventing collisions
If you are implementing lots of internal goop, do so with a common prefix or something that makes a collision with Apple provided (or third party) provided methods exceedingly unlikely. This is especially critical for categories and not nearly as critical for your leaf node subclasses of existing classes.
Post the link for the site suggesting leading underscores, as they are wrong, wrong, wrong. Leading underscores are used by the system to mark private API and you can run into collisions easily enough.
Hiding from the runtime.
Don't bother. It just makes debugging / crash analysis harder and anyone determined enough to muck around at the runtime will be able to hack your app anyway.
There are no "real" private methods in Objective C, as the run-time will allow, via documented public APIs, access any method in any class by using their string names.
I never do separate interface files for "private" methods, and let the compiler complain if I try to use these any of these methods outside of file scope.
The XX_ seems to be the ad hoc means to create a pseudo namespace. The idea is to read Apple's docs and the docs of any frameworks you might use at any time in the future, and pick an XX prefix that none of these others is ever likely to use.