I have rough ideas - like dealing with singular/plural, two or more words/phrases that mean the same thing, misspellings, etc. But I'm not sure of any patterns or rules of thumb for dealing with these, either programatically and automatically or by presenting them to administrators or even users to clean up.
Any thoughts or suggestions?
You should have a policy for the format of the tags (e.g. tags should be singular). Depending on how diverse the tags are, it might be useful not only to auto-complete while you are typing in a tag, but also to suggest similar tags, so that it is easy for people to use the tag system. Additionally, a cleanup process could correct common spelling mistakes and substitue deprecated tags according to a translation table.
As SO does, suggesting existing tags as you type is a very good thing.
It will (hopefully, almost) take care of the plural / singular thing and misspellings, as people will re-use existing tags much more.
Use an ajax-driven suggestion form, like StackOverflow :)
Assuming a setup not dissimiliar to SO: how about moderators being allowed to merge a smaller voted tag into a more common one, e.g. VS9 could be merged into VisualStudio2008 but not letting the larger used tag to be merged into a smaller tag grouping. Adding a badge incentive or similiar to this.
Related
I'm getting an error when uploading my customized policy, which is based on Microsoft's SocialAccounts example ([tenant] is a placeholder I added):
Policy "B2C_1A_TrustFrameworkExtensions" of tenant "[tenant].onmicrosoft.com" makes a reference to ClaimType with id "client_id" but neither the policy nor any of its base policies contain such an element
I've done some customization to the file, including adding local account signon, but comparing copies of TrustFrameworkExtensions.xml in the examples, I can't see where this element is defined. It is not defined in TrustFrameworkBase.xml, which is where I would expect it.
I figured it out, although it doesn't make sense to me. Hopefully this helps someone else running into the same issue.
The TrustFrameworkBase.xml is not the same in each scenario. When Microsoft documentation said not to modify it, I assumed that meant the "base" was always the same. The implication of this design is: If you try to mix and match between scenarios then you also need to find the supporting pieces in the TrustFrameworkBase.xml and move them into your extensions document. It also means if Microsoft does provide an update to their reference policies and you want to update, you need to remember which one you implemented originally and potentially which other ones you had to pull from or do line-by-line comparison. Not end of the world, but also not how I'd design an inheritance structure.
This also explains why I had to work through previous validation errors, including missing <DisplayName> and <Protocol> elements in the <TechnicalProfile> element.
Yes - I agree that is a problem.
My suggestion is always to use the "SocialAndLocalAccountsWithMfa" scenario as the sample.
That way you will always have the correct attributes and you know which one to use if there is an update.
It's easy enough to comment out the MFA stuff in the user journeys if you don't want it.
There is one exception. If you want to use "username" instead of "email", the reads/writes etc. are only in the username sample.
I'm currently working on a project, which has to be MISRA 2012 compliant. But in the embedded world, you can't fulfill every MISRA rule. So I have to suppress some messages generated by QA-C. What's he best solution to do this?
I was thinking about making a table in every module header file with references (\ref and \anchor) to the relevant code lines, a description, etc. The first problem is: I can't use the Doxygen markdown table feature, because then the description has to be in one line, because Doxygen tables don't support line breaking. So I thought about using a simple verbatim table, what do you think?
Or is there a way to generate such a table automatically?
Greetings
m0nKeY
According to MISRA, all such undesired rules must be handled by your deviation procedure, given that they are either "required" or "advisory". You are not allowed to deviate from "mandatory" rules. (Strictly speaking, you don't need to invoke the deviation procedure for advisory rules.)
In my experience, the safest and smoothest way by far to do this, is to not allow individual deviations on case-by-case basis. All deviations from MISRA should be stated in your company coding standard, and in order to deviate you have to update that document. Which in turn enforces approval from the document owner, who is preferably the most hardened C veteran you have in the team.
That way, you prevent less experienced team members from misinterpreting the rules and ignoring important rules, simply because they don't understand them and mistake them for false positives. There should be a rationale in the document stating why the rule you deviate from is not feasible for your company.
This means that everyone in the dev team is allowed to deviate from the listed rules at any point, without the need to invoke any form of bureaucracy.
Once you have a setup like this, simply customize your static analyser and remove/ignore the undesired warnings. That way, you get rid of a lot of noise and false warnings from the tool.
To answer your question generally: To create an aggregate occurrence list of anything in doxygen, use \xrefitem
We use this as a tool in our code review process. I tag code with a custom tag \reviewme which adds the function to a list of all code in need of peer review. The next guy can come along and clear that tag. We have another custom tag \reviewedby which does not use \xrefitem but simply puts the reivewers name and the date in the code block saying who reviewed it and when. This had gotten a bit clunky as things have scaled with larget code bases and more developers. Now we're looking into tools that integrate with our version control process to handle this better. But when we started this it worked well and fit a shoestring budget. But that example should give you an idea of is capable.
Here is a screen shot of what the output looks like - proprietary stuff and auto names redacted:
Here is how we added this custom tag as an alias to xrefitem in our doxy file as follows
ALIASES = "reviewme = \xrefitem reviewme \"This section needs peer review\" \"Documentation block or code sections that need peer review\""
To add it from the GUI, you would go to Expert->Project->Aliases and add a line like this
reviewme = \xrefitem reviewme "This section needs peer review" "Documentation block or code sections that need peer review"
Same thing, just no need to put quotes around the whole thing and escape out the inner quotes.
\xrefitem is the underpinning of how things like \todo or \bug work in doxygen. You can make a list of just about anything your heart desires.
Speaking specifically to MISRA exceptions: Lundin's post has lot's of merit. I would consider it. I think a better place to document exceptions to coding standards is in the static analysis tool its self. Many tools have their own annotations where you can categorize the rule violation as 'excused' or whatever. But generally this does not remove them from the list, it allows you just to filter or sort them. Perhaps you can use REGEX in a script that runs prior to doxygen that will replace the tool specific annotation with a custom \xrefitem if you are really concerned. Or vice vera, replace the doxy annotation with your tool's annotation.
Ui:include and xhtml based tag (the one with source elt) seem to be much the same for me. Both allow to reuse piece of markup. But I believe there should be some reason for having each. Could somebody please briefly explain it? (I guess if I read full facelets tutorial I will learn it, but I have not time to do it now, so no links to lengthy docs please :)
They are quite similar. The difference is mainly syntactical.
After observing their usage for some time it seems the convention is that fragments that you use only in a single situation are candidates for ui:include, while fragments that you re-use more often and have a more independent semantic are candidates for a custom tag.
E.g.
A single view might have a form with three sections; personal data, work history, preferences. If the page becomes unwieldy, you can divide it into smaller parts. Each of the 3 sections could be moved to their own Facelet file and will then be ui-include'ed into the original file.
On the other hand, you might have a specific way to display on image on many views in your application. Maybe you draw a line around it, have some text beneath it etc. Instead of repeating this over and over again you can abstract this to its own Facelet file again. Although you could ui:include it, most people seem to prefer to create a tag here, so you can use e.g. <my:image src="..." /> on your Facelets. This just looks nicer (more compact, more inline with other components).
In the Facelets version that's bundled with JSF 2.0, simple tags can be replaced by composite components. This is yet a third variant that on the first glance looks a lot like custom tags, but these things are technically different as they aren't merely an include but represent true components with declared attributes, ability to attach validators to, etc.
I have always viewed tags as completely different than the normal folder hierarchy model. I am building a system that needs tagging to tag sets of data. We had the db design all worked out, (pretty straightforward model) but a debate arose around the value of still having concepts of hierarchies within a world of tags.
On SOF, as an example, the only equivalent I see some of this by using - in some tag names like tagging; jquery, jquery-ui, jquery-ui-dialog so there is no inherent modeled relationship (just a naming convention).
Is there any conventional wisdom of best practices around how and if hierarchies should exist in a world of tagging?
I developed a portal that involved hierarchical tags. I can assure you that is a mess to manage :)
My solution then moved to a hybrid approach in which tags can be stand-alone or hiearchically handled but they reside in two different namespaces.
This because some tags can be seen as children of parents of other tags while others cannot, so for example dialog tag is a concept that is also indipendent from jquery so a content with both tags jquery dialog has implicitly the relationship needed.
Hierarchical should be used to express a kind of inheritance between concepts, eg. collections -> trees, lists, maps in which trees tag can be effectively included inside a collections tag.
In your example dialog and jquery are orthogonal and uncomparable, so it makes no sense to make one child of another.
The names "jquery", "jquery-ui", "jquery-ui-dialog" aren't tags, but the equivalent of file structure paths, hierarchical by nature.
If your data is easy to authoritatively categorize then present it as a tree. If users only see a few of their own tags (like in Gmail), you could make it possible to sort and nest the tag list and save that structure per user, separately from tags themselves. If there are great many tags with power distribution of content (for example if 10% of tags describe 90% of content) then a tag cloud can help.
In short, it depends on the data.
hierarchies have in general a disadvantage compared to sets.
think of bookmarks and tag-bundles like delicious.com.
i prefer to search for a set using sport and newer-than-1-week and ( english-language or chinese-language ) and not ( soccer or boxing ).
Say I come up with some super-duper way of representing some data that I think would be useful for other people to know about and use. Assume I have a 'spec' in some form, even if it might not be a completely formal one: ie, I know how this file format will work already.
How would I then go about releasing this spec to get comments and feedback based on it? How would I get it 'standardised' in some form?
Specifying file formats is difficult. If the data you want to store is trivial, it tends to be trivial. In general however, this is hardly the case. You can use the RFC structure and keywords, but I always found specifying a fileformat in prose a slow, difficult and boring task, also because reading it is likewise difficult.
My suggestion, if you want to follow this way, is to focus on blocks of information. Most of the difficuly is for entities that are optional, and present only if another condition happens, so try to exploit this when partitioning your data.
The best spec, IMHO, is real code with an uberperfect testsuite.
As for standardization, if enough people use it, it becomes a de-facto standard. you don't need an official stamp for it, although when the format is used enough, you could benefit from an official mime type.
To talk about it, well, it depends. I found useful to talk in terms of "object oriented" entities, and also in terms of relationships. Database-like diagrams are very useful on this respect.
Finally, try to find a decent already standard alternative first, or at least try not to deal with the raw bits. There are a lot of perfect container formats out there that free you of many annoying tasks. The choice of the container depends on the actual type of file format (e.g. if you need encryption, interleaving, transactions, etc).
There are a couple of ways I'd go about it, I think.
First, determine if there's a standards body (like W3C, or IEEE) that might be related to your file format. If there is, pitch it to them. I have no idea how receptive they'd be though.
Second, a standard is useless if nobody is using it. Get some momentum behind it. Write a blog post, twitter and make a website about it. Link on programming.reddit.com, and slashdot. Describe it to your friends and colleagues. Post it here on SO, and ask for feedback.
HTH.