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.
Related
I'm reading about the Laravel Best practices to reduce the code duplication as much as I can, then I read about the repository pattern and I'm following this technique but when I was exploring the https://github.com/akaunting/akaunting open source software for accounting, I saw there is nothing related to respository pattern. I really got confused, so when should I use the repository pattern? if it is helpful when why the good projects not use that pattern? or if there is something better than repository pattern?
This is true for every design pattern: never start with wanting to implement a specific design pattern.
Start by never using the repository pattern (or any other pattern) and when you feel like your controllers are getting really big or your code is getting really hard to maintain take a look at what design pattern might solve your issue.
The given package does not contain that pattern because the people who made it did not need an extra layer of abstraction or chose other abstraction solutions.
Always start simple.
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.
FxCop thought me (basically, from memory) that functions, classes and properties should be written in MajorCamelCase, while private variables should be in minorCamelCase.
I was talking about a reasonably popular project on IRC and quoted some code. One other guy, a fairly notorious troll who was also a half-op (gasp!) didn't seem to agree. Everything oughta be in the same casing, and he quite fervently favored MajorCamelCase, or even underscore_separation.
Ofcourse, he was just a troll so I reckoned I'd just keep doing it the way I already did. Before I learned the above guidelines, I hardly even had a coherent naming style.
He got me thinking, though -- does stuff like this really matter?
You need to make sure that your code is readable in the future. Please remember that you might want to pass the development of your application to someone else and this person will need to read and understand it. You could stop actively working on a project and return to it after a year - and be suprised that you have to read code carefully to understand how it works.
I believe it was Steve McConnell who said that specific naming style does not really matter (you could use anything you want as long as you are consistent) but this only applies when everyone working on the project agree with you.
In general it is better to adopt community-accepted coding styles where possible to facilitate code reuse and shorten learning curves.
If you don't care about long-term maintanability of your project (or consistency or readability) then no, casing (and coding conventions in general) don't really matter. Otherwise, they do matter. See this.
Your specific coding style doesn't matter (much), so long as it is consistent throughout the project.
This improves readability and understanding, as if an identifier is named in a particular way, the reader can (hopefully) be confident as to what that naming style implies.
As regards CamelCase v underscores, etc: again, it's down to your coding convention. One approach which uses both is to apply a prefix with underscore to indicate the module in which the function, or file-scope/global variable, is used, e.g. Config_Update(), Status_Get().
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.
How do YOU factor your Domain (namespaces), in Domain Driven Design?
I have been moving to the following concept:
Project.Entity
Project.Entity.Abstracts
Project.Entity.Entities
Project.Entity.Extensions
Project.Entity.Immutables
Project.Entity.Interfaces
Project.Entity.Repositories
For example, I have an entity in a CMS called "Content". So, I would create a project called Project.Content, and factor the classes to look like:
interface IContent
class Content : IContent
interface IContentRepository
class ContentRepository : IContentRepository
This "Content" Entity model would have its own namespace.
But, I am finding it does not scale well in a large Enterprise environment with well over a dozen projects (try 18) of "Entity" models. I end up with a solution with over a dozen projects, some of which only have 2 or 3 classes (i.e. UrlRewriter). Also, I find myself referencing other projects just for their Interfaces. I feel like this is poluting my domain; while not concret references, it's sometimes difficult to keep from circular references.
So, I fall back to the "Layer" concept at times...
I am wanting to know how other DDD experts are factoring Enterprise-size applications. Please feel free to recommend books and articles.
And thanks in advance!
One think that I do is to add something that identifies the bounded context to it.
Ps. to make sure it is clear why, check both links on bounded context:
http://dddcommunity.org/discussion/messageboardarchive/BoundedContext.html, http://devlicio.us/blogs/casey/archive/2009/02/11/ddd-bounded-contexts.aspx
I use follow the .NET guidelines. I find them very intuitive and they allow you to setup namespaces such that you don't need to import anything you don't need.
I would never impose a strict naming convention for the feature level. The design of each different project should guide that.
I similarily to you have found out that having load of projects becomes a pain to manage.
I prefer the
Project.Domain
Project.DataAccess
Project.Presentation (presenters and such)
Project.Gui (in case of a winforms app)
setup.
In a way making things simple helps a lot when things go bad.
The question is what do you gain when you create another project ? (it is very easy to do so, almost to easy)
Will you ever want to use that project independently or not ? You might end up with the resulting .dlls so coupled you can't even deploy them without being exactly the same versions etc. in that case there is little reason for splitting it up and cluttering your IDE)
You can always move things to a new project later if the need arises, it is somewhat painfull, but by that time you would have a good reason to do it apart from just the feeling that is the way it is done.