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
In Grails, there are two mechanisms for modularity in the view layers: Template and TagLib.
While I am writing my own Grails app, I am often facing the same question when I need to write an UI component: do I need to use a template or a TagLib?
After searching the web, I didn't find a lot of best practices or rules of thumb concerning this design decision, so can you help me and tell me:
What is the main difference between the two mechanisms?
In which scenarios, do you use a TagLib instead of a Template (and vice-versa) ?
There is definitely some overlap, but below are several things to think about. One way to think about it is that Template is like a method-level reuse, while TagLibs are more convenient for API-level reuse.
Templates are great for when you have to format something specific for display. For example, if you wan to display a domain object in a specific way, typically it's easier to do it in a template, since you are basically just writing HTML with some . It's reusable, but I think its reusability in a bit limited. I.e. if you have a template, you'd use it in several pages, not in hundreds of pages.
On the other hand, taglibs is a smaller unit of functionality, but one you are more likely to use in many places. In it you are likely to concatenate strings, so if you are looking to create a hundred lines of HTML, they are less convenient. A key feature taglibs allow is ability to inject / interact with services. For example, if you need a piece of code that calls up an authentication service and displays the current user, you can only do that in a TagLib. You don't have to worry about passing anything to the taglib in this case - taglib will go and figure it out from the service. You are also likely to use that in many pages, so it's more convenient to have a taglib that doesn't need parameters.
There are also several kinds of
taglibs, including ones that allow
you to iterate over something in the
body, have conditional, etc - that's
not really possible with templates.
As I said above, a well-crafted
taglib library can be used to create
a re-usable API that makes your GSP
code more readable. Inside the same *taglib.groovy you can have multiple tag definitions, so that's another difference - you can group them all in once place, and call from one taglib into another.
Also, keep in mind that you can call up a template from inside a taglib, or you can call taglibs withing templates, so you can mix and match as needed.
Hope this clears it up for you a bit, though really a lot of this is what construct is more convenient to code and how often it will be reused.
As for us...
A coder is supposed to see specific object presentation logic in template, not anywhere else.
We use taglibs only for isolated page elements, not related to business logic at all. Actually, we try to minimize their usage: it's too easy to write business logic in a taglib.
Templates are the conventional way to go; for instance, they support Layouts (btw, they can be named a third mechanism)
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 9 years ago.
Improve this question
Well, this is a pretty trivial question. But i'd like to know if it is okay to put multiple classes into one header / source file. I've often enough seen that for every class there is another header and another source file, like it is in Java (not only by Convention...)
I see the ups and downs here: on the one hand you might want to have some relevant classes on one place for editing, since big projects sometimes require you to search a bit for them. On the other hand, more files make single files less heavy, so you don't have to scroll down tousands of lines to get to the method you're searching.
Now what do the Conventions say about that?
[Example]
At the moment i have 3 classes in one file: a Server, A ClientHandler for the Server and a ServerManager.
The server manages the connections, the ClientHandler manages all in- and outgoing traffic for each client and the ServerManager contains some logic i need to run the Server.
[Edit] be gentle with my abilities of the english language, i'm foreign ;)
It's considered good form for each class to have its own header/implementation pair.
The most compelling reason (for me) is that the files are named after the class they contain. This makes it easy to find the correct file for a declaration in the code. If a file has more than one type in it, it becomes harder to name, and therefore harder to maintain.
However, sometimes it's not so clear cut. A "main" class might have some other supporting class that's definitely part of its interface (in the Herb Sutter sense of interface), but doesn't rightly belong as a nested type. This should be rare, but such a case might justify having more than one class per file.
If you've gone to the trouble of abstracting out concepts (such as in the example you give), why not go the extra little bit and put them in their own files? You will thank yourself for it down the line!
There's no real rule, other than common sense. If two classes
are closely linked, it's common to put them in the same header.
And of course, not everything in C++ is a class; free functions
may be grouped in various different headers according to
whatever seems most logical.
Also, there isn't always a one-to-one relationship between
headers and source files. If your class is a template, there
may not be a source file at all. On the other hand, if you're
writing a library that will be widely used, and the class isn't
polymorphic, you'll probably want to put each function in
a separate source file.
And a lot of classes are defined directly in source files, and not in headers.
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'm creating REST API that will be used by a web page.
There are several types of data I should provide, and I'm wondering what would be the best practice:
Create one method that will return a complex object with all the needed data.
Pros: one call will be needed from the UI side to get all the data.
Cons: not generic solution at all.
Create multiple autonomous method.
Pros: generic enough to be used in the future by other components.
Cons: will require the UI to make several calls to the server.
Which one adheres more to best practices?
It ultimately depends on your environment, the data-size and the quantity of methods. But there are several reasons to go with the second option and only one to go with the first.
First option: One complex method
Reason to go with the first: The HTTP overhead of multiple requests.
Does the overhead exist? Of course, but is it really that high? HTTP is one of the lightest application layer protocols. It is designed to have little overhead. It's simplicity and light headers are some of the main reasons to its success.
Second option: Multiple autonomous methods
Now there are several reasons to go with the second option. Even when the data is large, believe me, it still is a better option. Let's discuss some aspects:
If the data-size is large
Breaking data transfer into smaller pieces is better.
HTTP is a best effort protocol and data failures are very common, specially in the internet environment - so common they should be expected. The larger the data block, the greater the risks of having to re-request everything back.
Quantity of methods: Maintainability, Reuse, Componentization, Learnability, Layering...
You said yourself, a generic solution is easier to be used by other components. The simpler and more concise the methods' responsibilities are, the easier to understand them and reuse them in other methods it is.
It is easier to maintain, to learn: the more independent they are, the less one has to know to change it (or get rid of a bug!).
To take REST into consideration here is important, but the reasons to break down the components into smaller pieces really comes from understanding the HTTP protocol and good programming/software engineering.
So, here's the thing: REST is great. But not every pattern in its purest form works in every situation. If efficiency is an issue, go the one-call route. Or maybe supply both, if others will be consuming it and might not need to pull down the full complex object every time.
I'd say REST does not care about data normalization. Having two ways to get at the same data is not going to hurt.
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'm writing a C++ program that has a large number of classes. In my head I can visualise them as distinct collections. For example there's a collection of classes for reading and storing config data, and another collection for drawing a user interface with various widgets.
Each of those collections could be neatly stored inside separate namespaces, which seems sensible. The config part has a "screen" class, and the GUI part also has a "screen" class, but they are different to each other. I could rename one "gui_screen" and the other "config_screen", but that's the point of a namespace isn't it? To remove these prefixes we invent to separate things.
Part of me then thinks it'd be tidy to store those namespaces inside one main one so that none of my code can interfere with the namespaces of anything else. And I suppose it might also make the code more readable too.
Or am I just making overly complex hierarchies of data for no reason at all?
If you're having namespaces with common names such as "gui" and "config", and it's possible that your code may in the future be part of a library meant to be linked with other code not under your control, it might indeed be a good idea to nest all of "your" namespaces into a single named one (which probably should have no other content except the nested namespaces) which identifies them as "yours". There is really no penalty for doing so, especially if, as you think, it can be done in a way that helps readability. (That's quite different from deep nested hierarchies of class inheritance, which can definitely hamper clarity, as different functionality is added at each layer and a reader or maintainer of the code has to be jumping around among many files to see or change what's added where!-)
No, IMO you're not overdoing at all.
And resist the temptation to use using declarations or (heaven forbid!) using directives! It takes very little getting used to always typing all namespaces and, once you're used to it, it makes the code much easier to read and understand. ("Which screen type is this again, gui or config?")
Personally I've never seen more than two levels of namespace nesting that was at all meaningful or useful. What you've described sounds fine, but I wouldn't go any deeper than project::component unless you've got a tangible, demonstrable, "this breaks without it" reason to do so. In other words, foo::bar::screen is reasonable, foo::bar::ui::screen is highly questionable, and anything more than that almost certainly introduces more complexity than is justified.
It is not overkill. It is reasonable to nest your namespaces, e.g. piku::gui::screen etc.
You could also collapse them to piku_gui_screen, but with the separate, nested namespaces you get the advantage that, if you're inside piku::gui, you can access all names in that namespace easily (e.g. screen will automatically resolve to piku::gui::screen).
Defining namespaces you are not doing any hierarchy, so I don't see what the problem is, anyway namespace are there just to solve your very problem.
I personally love to group files/classes by their functionality. I normally start with a folder with a name that matches the namespace I will use. Eventually if a namespace needs to be reused in another application, you can easily take it out and build it into it's own dll and share it.
It also makes for nice intellisense so that when I'm drilling down through namespaces, I can see just the classes that are part of that group of functionality.
It seems to me that one namespace per developer ought to be enough -- you (presumably) have control over all the type names you define in your own code, and it's unlikely that you'll want to use the same type name for different types within the same project.
I think the main use of namespaces is to handle the case where two independent developers happened to choose the same type name -- without namespaces you'd have no way to use both developers' code in the same project. Multiple namespaces within a single developer's codebase, OTOH, just add complexity and typing overhead, with little or no compensating benefit.
All IMHO, of course.
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
What do you think is best practice when creating public header files in C++?
Should header files contain no, brief or massive documentation? I've seen everything from almost no documentation (relying on some external documentation) to large specifications of invariants, valid parameters, return values etc. I'm not sure exactly what I prefer, large documentation is nice since you've always access to it from your editor, on the other hand a header file with very brief documentation can often show a complete interface on one or two pages of text giving a much better overview of what's possible to do with a class.
Let's say I go with something like brief or massive documentation. I want something similar to javadoc where I document return values, parameters etc. What's the best convention for that in c++? As far as I can remember doxygen does good stuff with java doc-style documentation, but are there any other conventions and tools for this I should be aware of before going for javadoc style documentation?
Usually I put documentation for the interface (parameters, return value, what the function does) in the interface file (.h), and the documentation for the implementation (how the function does) in the implementation file (.c, .cpp, .m).
I write an overview of the class just before its declaration, so the reader has immediate basic information.
The tool I use is Doxygen.
I would definetely have some documentation in the header files themselves. It greatly improves debugging to have the information next to the code, and not in separate documents. As a rule of thumb, I would document the API (return values, argument, state changes, etc) next to the code, and high-level architectural overviews in separate documents (to give a broader view of how everything is put together; it's hard to place this together with the code, since it usually references several classes at once).
Doxygen is fine from my experience.
I believe Doxygen is the most common platform for generating documentation, and as far as I know, it's more or less able to cover JavaDoc-notation (not limited to of course). I've used doxygen for C, with OK results, I do think it's more suitable for C++ though. You might want to look into robodoc as well, although I think Occam's Razor will tell you to rather go for Doxygen.
Regarding how much documentation, I've never been a documentation-fan myself, but whether I like it or not, having more documentation always beats having no documentation. I'd put the API-documentation in the header file, and the implementation documentation in the implementation (stands to reason, doesn't it?). :) That way, IDEs have the chance to pick it up and show it during autocompletion (Eclipse does this for JavaDocs, for example, perhaps also for doxygen?), which shouldn't be underestimated. JavaDoc has this additional quirk that it uses the first sentence (i.e. up to the first full stop) as a brief description, don't know if Doxygen does this though, but if so, it should be taken into consideration when writing the documentation.
Having a lot of documentation runs the risk of being out of date, however, keeping the documentation close to the code will give people a chance to keep it up to date, so you should definately keep it in the source/header files. What shouldn't be forgotten though is the production of documentation. Yes, some people will use the documentation directly (through the IDE or whatever, or just reading the header file), but some people prefer other ways, so you should probably consider putting your (regularly updated) API documentation online, all nice and browsable, as well as perhaps producing man-files if you're targeting *nix-based developers.
That's my two cents.
Put enough into the code that it can stand alone. Nearly every project I've been in where the documentation was separate, it got out of date or wasn't done, partly that if it's a separate document it becomes a separate task, partly as management didn't allow for it as a task in budgetting. Documenting inline as part of the flow works much better in my experience.
Write the documentation in a form which most editors recognise is a block; for C++ this seems to be /* rather than //. That way you can fold it and just see the declarations.
Maybe you would be interested in gtk-doc. It can be "a bit awkward to setup and use" but you can get a nice API documentation from source code, looking like this:
String Utility Functions
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm working on a fairly big open source RTS game engine (Spring). I recently added a bunch of new C++ functions callable by Lua, and am wondering how to best document them, and at the same time also stimulate people to write/update documentation for a lot of existing Lua call-outs.
So I figured it may be nice if I could write the documentation initially as doxygen comments near the C++ functions - this is easy because the function body obviously defines exactly what the function does. However, I would like the documentation to be improved by game developers using the engine, who generally have little understanding of git (the VCS we use) or C++.
Hence, it would be ideal if there was a way to automatically generate apidocs from the C++ file, but also to have a wiki-like web interface to allow a much wider audience to update the comments, add examples, etc.
So I'm wondering, does there exist a web tool which integrates doxygen style formatting, wiki-like editing for those comments (preferably without allowing editing any other parts of the source file) and git? (to commit the comments changed through the web interface to a special branch)
We developers could then merge this branch every now and then to add the improvements to the master branch, and at the same time any improvements by developers to the documentation would end up on this web tool with just a merge of the master branch into this special branch.
I haven't found anything yet, doubt something this specific exists yet, so any suggestions are welcome!
This is a very cool idea indeed, and a couple of years ago I also had a very strong need for something like that. Unfortunately, at least back then, I wasn't able to find something like that. Doing a quick search on sourceforge and freshmeat also doesn't bring up anything related today.
But I agree that such a wiki frontend to user-contributed documentation would be very useful, I know for a fact that something like this was recently being discussed also within the Lua community (see this).
So, maybe we can determine the requirements in order to come up with a basic working draft/prototype?
Hopefully, this would get us going to initiate such a project with a minimum set of features and then simply release it into the wild as an open source project (e.g. on sourceforge), so that other users can contribute to it.
Ideally, one could use unified patches to apply changes that were contributed in such a fashion. Also, it would probably make sense to restrict modifications only to adding/editing comments, instead of allowing arbitrary modifications of text, this could probably be implemented by using a simple regex.
Maybe, one could implement something like that by modifying an existing (established) wiki software such as mediawiki. Or preferably something that's already using git as a backend for storage purposes. Then, one would mainly need to cater for those Doxygen-style comments, and provide a simple interface on top of it.
Thinking about it some more, DoxyGen itself already provides support for generating HTML documentation, so from that perspective it might actually be interesting to see, how DoxyGen could possibly be extended, so that it is well integrated with such a scripted backend that allows for easy customization of embedded source code documentation.
This would probably mainly boil down to providing a standalone script with doxygen (e.g. in python, php or perl) and then optionally embed forms in the automatically created HTML documentation, so that documentation fixes/augmentations can be sent to the corresponding script via a browser, which in turn would write any modifications back to a corresponding branch.
In the long term, it would be cool if such a script would support different types of backends (CVS, SVN or git), or at least be implemented generically enough, so that it is easily extendible.
So, if we can come up with a good design, it might even be possible that such a modification would be generally accepted as a contribution to doxygen itself, which would also give the whole thing much more exposure and momentum.
Even if the idea doesn't directly materialize into a real project, it would be interesting to see how many other users actually like the idea, so that it could possibly be mentioned in the doxygen issue tracker (https://github.com/doxygen/doxygen/issues/new).
EDIT: You may also want to check out this article titled "Documentation, Git and MediaWiki".