I have read several good articles on the Maven versioning with well known qualifiers. However, I found it interesting that after the so called 'final' release which is an empty qualifier, ga, or final I can't find any article that describes how the sp qualifier might be used. Evidently it compares greater than the final qualifier, but I've no idea of the letters stand for something in particular or if there is some popular software release convention that uses that qualifier. rc would typically mean release candidate, so I would think that sp would have some kind of meaning and that the letters were chosen in accordance with some kind of pattern.
Here is one of the articles I've already read, and I see no info that would give me a hint as to what sp means or how it might be used.
https://cwiki.apache.org/confluence/display/MAVENOLD/Versioning
AFAIK this stands for "service pack" and therefore describes corrections/additions after the final release.
Related
It seems that some conformance resources are written to prescribe fixed URLs (with or without version suffix), for example by constraining meta.profile to a fixedCanonical.
{
"id": "Invoice.meta.profile",
"path": "Invoice.meta.profile",
"fixedCanonical": "http://zrbj.eu/StructureDefinition/foo|1.2.3"
}
This means that users always MUST specify the URL exactly as specified, i.e. with or without version, and the builtin flexibility of the FHIR mechanisms goes down the drain.
If I leave off the constraint then it is the user's choice whether to specify a version or not. Given a profile http://zrbj.eu/StructureDefinition/foo with version 1.2.3 the following four canonicals all work as expected in meta.profile of resource instances:
http://zrbj.eu/StructureDefinition/foo
http://zrbj.eu/StructureDefinition/foo|1.2
http://zrbj.eu/StructureDefinition/foo|1.2.2
http://zrbj.eu/StructureDefinition/foo|1.2.3
http://zrbj.eu/StructureDefinition/foo|1.2.4
The fifth example (resource with higher patch level than the profile) may be slightly counter-intuitive but that is how semantic versioning (SemVer) is supposed to function here: if major and minor version correspond then a resource with lower patch level must be accepted by a profile version with higher patch level and vice versa (i.e. compatibility goes both ways).
The following canonicals do not match major.minor of the profile and are rejected, as expected:
http://zrbj.eu/StructureDefinition/foo|1
http://zrbj.eu/StructureDefinition/foo|1.1
http://zrbj.eu/StructureDefinition/foo|1.3
Our usage scenario calls for the second accepted case: resources must 'commit' to one of the structural versions (major.minor) defined as permissible on the day of their creation, and they must document this by specifying the chosen version in the URL suffix. This still leaves the profile author free to fix minor things and increment the patch level, as long as two-way compatibility is preserved. It also offers a way of fixing certain classes of bugs with the least amount of collateral damage.
Is there anything that speaks against leaving off the URL-fixing constraint, given a usage scenario as the one I described?
UPDATE
Lloyd McKenzie has pointed out that extension URLs cannot be versioned. Hence I have rewritten the examples to use meta.profile instead.
Extension.url is defined as having a type of "uri", not "canonical". That means that version-specific references are not permitted. The version of the extension "in play" is driven by the version of the core specification in play and/or the versions of the IGs declared in the CapabilityStatement of the server. If neither of these define the extension, then the version of the extension may be ambiguous. For this reason, its important to not significantly change the semantics of an extension over time - instead, if needed, define a new extension.
There is currently no conformant mechanism of declaring the 'version' of an extension in an instance. If this is an essential requirement for you, submit a change request using the "propose a change" link at the bottom of any page in the spec and the community can discuss alternatives. (Given that Extension is now normative, it is extremely unlikely that changing to allow the 'canonical' syntax will be the agreed solution, as that would be a breaking change.)
Does anybody know the difference between those two terms? In my opinion both refer to exactly the same thing: a framework or API, for which only unconventional behavior must be specified. If there is a difference, could you share with example, in which one term is acceptable, and second one not?
IMHO both refers to the same. Nice examples to it are Maven and JPA.
We're doing a big project on OSGi and adding some commons modules. There's some discussion about naming the artifact.
So, one possibility when naming the module is for example:
cmns-definitions (for common definitions), another is cmns-definition, still another is cmns-def. This has some effect also on the package name. Now it's
xx.xxx.xxx.xxx.xxx.commons.definitions, if changing to cmns-def it would be xx.xxx.xxx.xxx.xxx.commons.def.
Inside this package will be classes like enums and other definitions to be used throughout the system.
I personally lean to cmns-definitions since there's not only 1 definition inside the package. Other people point out that java.util doesn't have only 1 utility there for example. Still, java.util is an abbreviation for me. It can mean java utility or java utilities. Same thing happens with commons-lang.
How would you name the package? Why would you choose this name?
cmns-definitions
cmns-definition
cmns-def
Bonus question: How to name something like cmns-exceptions? That's how I name it. Would you name it cmns-xcpt?
ËDIT:
I'm throwing in my own thoughts on this in the hope of being either confirmed or contradicted. If you can, please do.
According to what I think, the background reason why you name something is to make it easier to understand what's inside it. Or, according to Peter Kriens, to make it easy to remember and being able to automate processes via patterns. Both are valid arguments.
My reasoning is as follows in terms of pattern:
1) When a substantivation occurs and it's well known in the industry, follow it on your naming.
Eg:
"features" is a case on this. We have a module called cmns-features. Does this mean we have many features on this module? No. It means "the module that implements the "features" file from Apache karaf".
"commons" is a substantivation of "common" well-accepted on the industry. It doesn't mean "many common". It means "Common code".
If I see extr-commons as a module name, I know that it contains common code for extr (in this case extraction), for example.
2) When a quantity of classes inside the module are cooperating to give a distinct "one and one only" meaning to the whole, use singular form to name it.
The majority of modules are included here. If I name something cmns-persistence-jpa, I mean that whatever classes inside cooperate together to provide the jpa implementation of cmns-persistence-api. I don't expect 2 implementations inside it, but actually a myriad of classes that together make one implementation. Crystal clear to me. No?
3) When a grouping of classes is done with the sole purpose of gathering classes by affinity, but the classes don't cooperate together to no purpose, use plural.
Here is the case for example of cmns-definitions (enums used by the whole system).
Alternatively, using an abbreviation circumvents the problem, e.g. cmns-def which can be also "interpreted expanded" by a human reader to cmns-definitions. Many people use also "xxxx-util" meaning xxxx-utilities.
Still a third option can be used to pack things together, using a name that itself means a pluralization. The word "api" comes to mind, but any word that pluralizes something would do, like "pack".
Support to these cases (3) are well-known modules like commons-collections (using the plural) or commons-dbcp (using abbreviation) or commons-lang (again abbreviation) and anything that uses api to pack classes together by affinity.
From apache:
commons-collections -> many powerful data structures that accelerate development of most significant Java applications
commons-lang -> host of helper utilities for the java.lang API
commons-dbcp -> package of several database connection pools
'it is just a name ...'
I find in my long career that these just names can make a tremendous difference in productivity. I do not think it makes a difference if you use definitions, definition, or def as long as you're consistent and use patterns in the name that are easy to remember and can be used to automate processes. A build based on a consistent naming scheme is infinitely easier to work with than a build with "nice human display" names that are ad-hoc and have no discernible pattern.
If you use patterns, names tend to become shorter. Now people working with these names usually spent a lot of time with them. So their readability is not nearly as important as their mnemonic value. It turns out that abbreviations of 3 or 4 characters are surprisingly powerful. One of the reason is they work well is that there is only one possible abbreviation while if you go longer there are many candidates.
Anyway, most import part is the overall consistency. Good luck.
definitions (or def or definition) is a bad name because it doesn't have any semantic to a reader. You're in an object oriented world (I suppose) - try to follow its conventions and principles. Modules in Maven should be named after the biggest "abstraction" they contain. "Definition" is a form, not a meaning.
Your question is similar to: "Which class name is better FileUtilities or FileUtils". Answer: none.
Basically what you do with the Definitions and Exceptions is to provide kind of an API for your other modules. So I propose to combine definitions, exceptions and add interfaces to it. Then it makes sense to call it all cmns-api. I normally prefer the singular names as they are shorter but you are free to decide as it is just a name.
I'm considering how to do automatic bug tracking and as part of that I'm wondering what is available to match source code line numbers (or more accurate numbers mapped from instruction pointers via something like addr2line) in one version of a program to the same line in another. (Assume everything is in some kind of source control and is available to my code)
The simplest approach would be to use a diff tool/lib on the files and do some math on the line number spans, however this has some limitations:
It doesn't handle cross file motion.
It might not play well with lines that get changed
It doesn't look at the information available in the intermediate versions.
It provides no way to manually patch up lines when the diff tool gets things wrong.
It's kinda clunky
Before I start diving into developing something better:
What already exists to do this?
What features do similar system have that I've not thought of?
Why do you need to do this? If you use decent source version control, you should have access to old versions of the code, you can simply provide a link to that so people can see the bug in its original place. In fact the main problem I see with this system is that the bug may have already been fixed, but your automatic line tracking code will point to a line and say there's a bug there. Seems this system would be a pain to build, and not provide a whole lot of help in practice.
My suggestion is: instead of trying to track line numbers, which as you observed can quickly get out of sync as software changes, you should decorate each assertion (or other line of interest) with a unique identifier.
Assuming you're using C, in the case of assertions, this could be as simple as changing something like assert(x == 42); to assert(("check_x", x == 42)); -- this is functionally identical, due to the semantics of the comma operator in C and the fact that a string literal will always evaluate to true.
Of course this means that you need to identify a priori those items that you wish to track. But given that there's no generally reliable way to match up source line numbers across versions (by which I mean that for any mechanism you could propose, I believe I could propose a situation in which that mechanism does the wrong thing) I would argue that this is the best you can do.
Another idea: If you're using C++, you can make use of RAII to track dynamic scopes very elegantly. Basically, you have a Track class whose constructor takes a string describing the scope and adds this to a global stack of currently active scopes. The Track destructor pops the top element off the stack. The final ingredient is a static function Track::getState(), which simply returns a list of all currently active scopes -- this can be called from an exception handler or other error-handling mechanism.
This doesn't have to be Java, but it's what I'm dealing with. Also, not so much concerned with the methods and details of those, I'm wondering about the overall class file.
What are some of the things I really need to have in my comments for a given class file? At my corporation, the only things I really can come up with:
Copyright/License
A description of what the class does
A last modified date?
Is there anything else which should be provided?
One logical thing I've heard is to keep authors out of the header because it's redundant with the information already being provided via source control.
Update:
JavaDoc can be assumed here, but I'm really more concerned about the details of what's good to include content-wise, whether it's definitive meta-data that can be mined, or the more loose, WHY etc...
One logical thing I've heard is to keep authors out of the header because it's redundant
with the information already being provided via source control.
also last modified date is redundant
I use a small set of documentation patterns:
always documenting about thread-safety
always documenting immutability
javadoc with examples
#Deprecation with WHY and HOW to replace the annotated element
keeping comments at minimum
No to the "last modified date" - that belongs in source control too.
The other two are fine. Basically concentrate on the useful text - what the class does, any caveats around thread safety, expected usage etc.
Implementation comments should usually be about why you're doing something non-obvious - and should therefore be rare. (For instance, it could be because some API behaves in an unusual way, or because there's a useful shortcut you can use but which isn't immediately obvious.)
For the sanity of yourself and future developers, you really ought to be writing Javadocs.
When you feel the need to write comments to explain what some code does, improve the readability of the code, so that comments are not needed. You can do that by renaming methods/fields/classes to have more meaningful names, and by splitting larger methods into smaller methods using the composed method pattern.
If even after all your efforts the code is not self-explanatory, for example the reason why some unobvious code had to be written is not clear from the code, then apologize by writing comments. (Sometimes you can document the reasons by writing a test which will fail, if somebody changes the unobvious-but-correct code to do the obvious-but-wrong thing. But having a comment in addition to that is also useful. I prefix such comments often with "// HACK:" or "// XXX:".)
An overall description of the purpose of the class, a description for each field and a contract for each method. Javadoc format works well.
If you assign ownership of components to particular developers or teams, owners should be recorded in the component source or VCS metadata.