Method Naming

[shapper]

Hello,

This might be a strange question but I am creating a few repositories
and I am looking how should I name my methods. I have been looking in
C# and I came up with the following:

public interface IAlbumRepository {

void Add(Album album);
IQueryable<Album> FindAll();
Album FindById(Int32 id);
void Remove(Int32 id);
void Save();
void Update(Album album);

} // IAlbumRepository

What do you think?
Previously I had "Create", "Delete", etc.

But I think this is maybe closer to what is usually done. Not?

Thanks,
Miguel

 

[Peter Duniho]

[...]
public interface IAlbumRepository {

void Add(Album album);
IQueryable<Album> FindAll();
Album FindById(Int32 id);
void Remove(Int32 id);
void Save();
void Update(Album album);

} // IAlbumRepository

What do you think?
Previously I had "Create", "Delete", etc.

Your question isn't very clear. Are you suggesting "Add" instead of
"Create" and "Remove" instead of "Delete"? If so, then I agree "Add" is
better than "Create". "Create" implies something new is being created
but a) you don't return a new object, and b) as far as I can tell from
the question, you really are only adding an existing object, not
creating a new one.

If you really liked the word "create", you could lengthen the method
name to something like "CreateNewRepositoryEntry", but you are still
left with the oddity that a method that is supposedly creating something
never actually returns the thing that has been created. I think "Add"
is better.

As far as "Delete" vs "Remove", they are more synonymous and so there's
less of a clear advantage of one over the other. "Remove" tends to be
more consistent with usage elsewhere in .NET, and has a less destructive
feel to it. That is, "Delete" might imply to some that the thing being
deleted is itself being destroyed. "Remove" is probably better, because
it makes clear that only the repository itself is affected.

Without specifics, I can't comment on the "etc." you mention.

Pete

 

[shapper]

[...]
  public interface IAlbumRepository {

    void Add(Album album);
    IQueryable<Album> FindAll();
    Album FindById(Int32 id);
    void Remove(Int32 id);
    void Save();
    void Update(Album album);

  } // IAlbumRepository

What do you think?
Previously I had "Create", "Delete", etc.

Your question isn't very clear.  Are you suggesting "Add" instead of
"Create" and "Remove" instead of "Delete"?  If so, then I agree "Add" is
better than "Create".  "Create" implies something new is being created
but a) you don't return a new object, and b) as far as I can tell from
the question, you really are only adding an existing object, not
creating a new one.

If you really liked the word "create", you could lengthen the method
name to something like "CreateNewRepositoryEntry", but you are still
left with the oddity that a method that is supposedly creating something
never actually returns the thing that has been created.  I think "Add"
is better.

As far as "Delete" vs "Remove", they are more synonymous and so there's
less of a clear advantage of one over the other.  "Remove" tends to be
more consistent with usage elsewhere in .NET, and has a less destructive
feel to it.  That is, "Delete" might imply to some that the thing being
deleted is itself being destroyed.  "Remove" is probably better, because
it makes clear that only the repository itself is affected.

Without specifics, I can't comment on the "etc." you mention.

Pete

Hi,

Basically the repositories works with a SQL database using Linq to SQL
or with XML files using Linq to XML.
I have two versions of the repository to use in different projects.

I am just trying to have consistent naming.

I was looking at Linq To SQL code and other NET code and I ended up
with:

Add - Add an object
Remove - Remove an object
Update - Update an object
Save - Commit the session

FindById - Find an object by id that might exist or not. So I use find
instead of Get. And get is also related with properties so Find seems
ok.

FindAll - Find all. Get could be used but there is one case where
nothing can be found. When it is empty.
However this is the case where I agree that FindAll or
GetAll could be ok.
But keeping Find is consistent with FindById, FindByName,
etc.

Well this is what I concluded after searching MSFT code.

What do you think?

Thank You,
Miguel

 

[Arne Vajhøj]

[...]
public interface IAlbumRepository {

void Add(Album album);
IQueryable<Album> FindAll();
Album FindById(Int32 id);
void Remove(Int32 id);
void Save();
void Update(Album album);

} // IAlbumRepository

What do you think?
Previously I had "Create", "Delete", etc.

Your question isn't very clear. Are you suggesting "Add" instead of
"Create" and "Remove" instead of "Delete"? If so, then I agree "Add" is
better than "Create". "Create" implies something new is being created
but a) you don't return a new object, and b) as far as I can tell from
the question, you really are only adding an existing object, not
creating a new one.

If you really liked the word "create", you could lengthen the method
name to something like "CreateNewRepositoryEntry", but you are still
left with the oddity that a method that is supposedly creating something
never actually returns the thing that has been created. I think "Add"
is better.

As far as "Delete" vs "Remove", they are more synonymous and so there's
less of a clear advantage of one over the other. "Remove" tends to be
more consistent with usage elsewhere in .NET, and has a less destructive
feel to it. That is, "Delete" might imply to some that the thing being
deleted is itself being destroyed. "Remove" is probably better, because
it makes clear that only the repository itself is affected.

Without specifics, I can't comment on the "etc." you mention.

Basically the repositories works with a SQL database using Linq to SQL
or with XML files using Linq to XML.
I have two versions of the repository to use in different projects.

I am just trying to have consistent naming.

I was looking at Linq To SQL code and other NET code and I ended up
with:

Add - Add an object
Remove - Remove an object
Update - Update an object
Save - Commit the session

FindById - Find an object by id that might exist or not. So I use find
instead of Get. And get is also related with properties so Find seems
ok.

FindAll - Find all. Get could be used but there is one case where
nothing can be found. When it is empty.
However this is the case where I agree that FindAll or
GetAll could be ok.
But keeping Find is consistent with FindById, FindByName,
etc.

Well this is what I concluded after searching MSFT code.

What do you think?

Update is fine.

Remove or Delete are both fine.

You Add something existing to something existing but you have
something existing Create something new.

FindAll and FindByXxx fine.

If Save is really a Commit, then I think you should
call it Commit.

Arne

 

[shapper]

shapper wrote:
[...]
   public interface IAlbumRepository {
     void Add(Album album);
     IQueryable<Album>  FindAll();
     Album FindById(Int32 id);
     void Remove(Int32 id);
     void Save();
     void Update(Album album);
   } // IAlbumRepository
What do you think?
Previously I had "Create", "Delete", etc.
Your question isn't very clear.  Are you suggesting "Add" instead of
"Create" and "Remove" instead of "Delete"?  If so, then I agree "Add" is
better than "Create".  "Create" implies something new is being created
but a) you don't return a new object, and b) as far as I can tell from
the question, you really are only adding an existing object, not
creating a new one.
If you really liked the word "create", you could lengthen the method
name to something like "CreateNewRepositoryEntry", but you are still
left with the oddity that a method that is supposedly creating something
never actually returns the thing that has been created.  I think "Add"
is better.
As far as "Delete" vs "Remove", they are more synonymous and so there's
less of a clear advantage of one over the other.  "Remove" tends to be
more consistent with usage elsewhere in .NET, and has a less destructive
feel to it.  That is, "Delete" might imply to some that the thing being
deleted is itself being destroyed.  "Remove" is probably better, because
it makes clear that only the repository itself is affected.
Without specifics, I can't comment on the "etc." you mention.

Basically the repositories works with a SQL database using Linq to SQL
or with XML files using Linq to XML.
I have two versions of the repository to use in different projects.

I am just trying to have consistent naming.

I was looking at Linq To SQL code and other NET code and I ended up
with:

Add - Add an object
Remove - Remove an object
Update - Update an object
Save - Commit the session

FindById - Find an object by id that might exist or not. So I use find
instead of Get. And get is also related with properties so Find seems
ok.

FindAll - Find all. Get could be used but there is one case where
nothing can be found. When it is empty.
           However this is the case where I agree that FindAll or
GetAll could be ok.
           But keeping Find is consistent with FindById, FindByName,
etc.

Well this is what I concluded after searching MSFT code.

What do you think?

Update is fine.

Remove or Delete are both fine.

You Add something existing to something existing but you have
something existing Create something new.

FindAll and FindByXxx fine.

If Save is really a Commit, then I think you should
call it Commit.

What is the difference?

In my session I have commit because it commits all changes done by all
the repositories that use that session:

public partial class Context : ISession
public void Save() {
SaveChanges();
}
}

And I also have Rollback do discard the changes.

I used Commit and Rollback because the code I found online of
UnitOfWork that wrapp various repositories use that.

But save seems ok to and more inline with LinqToSql.

But in fact LinqToSQL

 

[shapper]

shapper wrote:
[...]
   public interface IAlbumRepository {
     void Add(Album album);
     IQueryable<Album>  FindAll();
     Album FindById(Int32 id);
     void Remove(Int32 id);
     void Save();
     void Update(Album album);
   } // IAlbumRepository
What do you think?
Previously I had "Create", "Delete", etc.
Your question isn't very clear.  Are you suggesting "Add" instead of
"Create" and "Remove" instead of "Delete"?  If so, then I agree "Add" is
better than "Create".  "Create" implies something new is being created
but a) you don't return a new object, and b) as far as I can tell from
the question, you really are only adding an existing object, not
creating a new one.
If you really liked the word "create", you could lengthen the method
name to something like "CreateNewRepositoryEntry", but you are still
left with the oddity that a method that is supposedly creating something
never actually returns the thing that has been created.  I think "Add"
is better.
As far as "Delete" vs "Remove", they are more synonymous and so there's
less of a clear advantage of one over the other.  "Remove" tends to be
more consistent with usage elsewhere in .NET, and has a less destructive
feel to it.  That is, "Delete" might imply to some that the thing being
deleted is itself being destroyed.  "Remove" is probably better, because
it makes clear that only the repository itself is affected.
Without specifics, I can't comment on the "etc." you mention.

Basically the repositories works with a SQL database using Linq to SQL
or with XML files using Linq to XML.
I have two versions of the repository to use in different projects.

I am just trying to have consistent naming.

I was looking at Linq To SQL code and other NET code and I ended up
with:

Add - Add an object
Remove - Remove an object
Update - Update an object
Save - Commit the session

FindById - Find an object by id that might exist or not. So I use find
instead of Get. And get is also related with properties so Find seems
ok.

FindAll - Find all. Get could be used but there is one case where
nothing can be found. When it is empty.
           However this is the case where I agree that FindAll or
GetAll could be ok.
           But keeping Find is consistent with FindById, FindByName,
etc.

Well this is what I concluded after searching MSFT code.

What do you think?

Update is fine.

Remove or Delete are both fine.

You Add something existing to something existing but you have
something existing Create something new.

FindAll and FindByXxx fine.

If Save is really a Commit, then I think you should
call it Commit.

Arne

In fact when using Entity Framework I have:

public partial class Context : ISession {
public void Commit() {
SaveChanges();
} // Commit
public void Rollback() {
Dispose();
} // Rollback
}

But probably I should simple use Save instead of Commit and Dispose
instead of Rollback ...

 

[Arne Vajhøj]

On Mar 14, 10:44 pm, Peter Duniho<[email protected]>
wrote:
shapper wrote:
[...]
public interface IAlbumRepository {

void Add(Album album);
IQueryable<Album> FindAll();
Album FindById(Int32 id);
void Remove(Int32 id);
void Save();
void Update(Album album);

} // IAlbumRepository

What do you think?
Previously I had "Create", "Delete", etc.

Your question isn't very clear. Are you suggesting "Add" instead of
"Create" and "Remove" instead of "Delete"? If so, then I agree "Add" is
better than "Create". "Create" implies something new is being created
but a) you don't return a new object, and b) as far as I can tell from
the question, you really are only adding an existing object, not
creating a new one.

If you really liked the word "create", you could lengthen the method
name to something like "CreateNewRepositoryEntry", but you are still
left with the oddity that a method that is supposedly creating something
never actually returns the thing that has been created. I think "Add"
is better.

As far as "Delete" vs "Remove", they are more synonymous and so there's
less of a clear advantage of one over the other. "Remove" tends to be
more consistent with usage elsewhere in .NET, and has a less destructive
feel to it. That is, "Delete" might imply to some that the thing being
deleted is itself being destroyed. "Remove" is probably better, because
it makes clear that only the repository itself is affected.

Without specifics, I can't comment on the "etc." you mention.
Basically the repositories works with a SQL database using Linq to SQL
or with XML files using Linq to XML.
I have two versions of the repository to use in different projects.

I am just trying to have consistent naming.

I was looking at Linq To SQL code and other NET code and I ended up
with:

Add - Add an object
Remove - Remove an object
Update - Update an object
Save - Commit the session

FindById - Find an object by id that might exist or not. So I use find
instead of Get. And get is also related with properties so Find seems
ok.

FindAll - Find all. Get could be used but there is one case where
nothing can be found. When it is empty.
However this is the case where I agree that FindAll or
GetAll could be ok.
But keeping Find is consistent with FindById, FindByName,
etc.

Well this is what I concluded after searching MSFT code.

What do you think?

Update is fine.

Remove or Delete are both fine.

You Add something existing to something existing but you have
something existing Create something new.

FindAll and FindByXxx fine.

If Save is really a Commit, then I think you should
call it Commit.

In fact when using Entity Framework I have:

public partial class Context : ISession {
public void Commit() {
SaveChanges();
} // Commit
public void Rollback() {
Dispose();
} // Rollback
}

But probably I should simple use Save instead of Commit and Dispose
instead of Rollback ...

Why?

If the methods have the semantics of Commit and
Rollback, then use the names that gives the readers
the correct associations.

Arne

 

[Arne Vajhøj]

On Mar 14, 10:44 pm, Peter Duniho<[email protected]>
wrote:
shapper wrote:
[...]
public interface IAlbumRepository {

void Add(Album album);
IQueryable<Album> FindAll();
Album FindById(Int32 id);
void Remove(Int32 id);
void Save();
void Update(Album album);

} // IAlbumRepository

What do you think?
Previously I had "Create", "Delete", etc.

Your question isn't very clear. Are you suggesting "Add" instead of
"Create" and "Remove" instead of "Delete"? If so, then I agree "Add" is
better than "Create". "Create" implies something new is being created
but a) you don't return a new object, and b) as far as I can tell from
the question, you really are only adding an existing object, not
creating a new one.

If you really liked the word "create", you could lengthen the method
name to something like "CreateNewRepositoryEntry", but you are still
left with the oddity that a method that is supposedly creating something
never actually returns the thing that has been created. I think "Add"
is better.

As far as "Delete" vs "Remove", they are more synonymous and so there's
less of a clear advantage of one over the other. "Remove" tends to be
more consistent with usage elsewhere in .NET, and has a less destructive
feel to it. That is, "Delete" might imply to some that the thing being
deleted is itself being destroyed. "Remove" is probably better, because
it makes clear that only the repository itself is affected.

Without specifics, I can't comment on the "etc." you mention.
Basically the repositories works with a SQL database using Linq to SQL
or with XML files using Linq to XML.
I have two versions of the repository to use in different projects.

I am just trying to have consistent naming.

I was looking at Linq To SQL code and other NET code and I ended up
with:

Add - Add an object
Remove - Remove an object
Update - Update an object
Save - Commit the session

FindById - Find an object by id that might exist or not. So I use find
instead of Get. And get is also related with properties so Find seems
ok.

FindAll - Find all. Get could be used but there is one case where
nothing can be found. When it is empty.
However this is the case where I agree that FindAll or
GetAll could be ok.
But keeping Find is consistent with FindById, FindByName,
etc.

Well this is what I concluded after searching MSFT code.

What do you think?

Update is fine.

Remove or Delete are both fine.

You Add something existing to something existing but you have
something existing Create something new.

FindAll and FindByXxx fine.

If Save is really a Commit, then I think you should
call it Commit.

What is the difference?

Save = save single object that is either new or has been modified
Commit = commit a bunch of additions, modifications and deletions

Very different.

In my session I have commit because it commits all changes done by all
the repositories that use that session:

public partial class Context : ISession
public void Save() {
SaveChanges();
}
}

SaveChanges would be a lot better than Save, but I still
prefer Commit.

But save seems ok to and more inline with LinqToSql.

But in fact LinqToSQL

Good names should depend on functionality not on
technology.

Arne

 

[Peter Duniho]

[...]

What is the difference?

Save = save single object that is either new or has been modified
Commit = commit a bunch of additions, modifications and deletions

Very different.

How so?

Given an XDocument, you can add, modify, and delete within the
XDocument. Calling the Save() method "commits" those changes to a file.

Similarly, there's no reason an object that has a "Commit()" method must
support "additions" or "deletions".

One could imagine a bitmap object, for example, that is associated with
a specific file or other storage and which has a "Commit()" method that
saves the current state after modifications. What does an "addition" or
"deletion" look like in that scenario, and why are those things a
mandatory element of something with a "Commit()" method?

I will agree that the database domain has a language all its own that
people don't normally apply to simple objects or files. But there is
definitely an extent to which the operations found in both domains are
actually quite similar.

This is, in fact, why Miguel is able to write this generalized code that
works both with a database and an XML file. At the layer he's talking
about, the operations look the same.

If he's got a layer that abstracts the database away, so that the client
code doesn't really need to know of it, why should the database-domain
language necessarily be the only choice for naming?

[...]
Good names should depend on functionality not on
technology.

I agree with that, but don't feel it offers much guidance in terms of
naming here. The fact is, "saving" is the same as "committing" in this
context. You don't need a brand new object to be able to "save" it, and
additions or deletions _are_ in fact modifications to the object being
saved here, so the phrase "additions, modifications, and deletions" is
simply one word, with two extra ones thrown in that don't add anything.

Pete

 

[Arne Vajhøj]

[...]

If Save is really a Commit, then I think you should
call it Commit.

What is the difference?

Save = save single object that is either new or has been modified
Commit = commit a bunch of additions, modifications and deletions

Very different.

How so?

Given an XDocument, you can add, modify, and delete within the
XDocument. Calling the Save() method "commits" those changes to a file.

That is because the XDocument here is a single object that is being
modified - it is not being added or deleted.

Parts of the document is being added or deleted, but the Save
does not refer to the parts.

Similarly, there's no reason an object that has a "Commit()" method must
support "additions" or "deletions".

That is the expectation from Commit.

One could imagine a bitmap object, for example, that is associated with
a specific file or other storage and which has a "Commit()" method that
saves the current state after modifications. What does an "addition" or
"deletion" look like in that scenario, and why are those things a
mandatory element of something with a "Commit()" method?

That is again a single object.

I will agree that the database domain has a language all its own that
people don't normally apply to simple objects or files. But there is
definitely an extent to which the operations found in both domains are
actually quite similar.

This is, in fact, why Miguel is able to write this generalized code that
works both with a database and an XML file. At the layer he's talking
about, the operations look the same.

If he's got a layer that abstracts the database away, so that the client
code doesn't really need to know of it, why should the database-domain
language necessarily be the only choice for naming?

Database language is not necessarily the only choice, but Commit is
not a database specific term.

Think EJB, CORBA and COM+.

[...]
Good names should depend on functionality not on
technology.

I agree with that, but don't feel it offers much guidance in terms of
naming here. The fact is, "saving" is the same as "committing" in this
context. You don't need a brand new object to be able to "save" it, and
additions or deletions _are_ in fact modifications to the object being
saved here, so the phrase "additions, modifications, and deletions" is
simply one word, with two extra ones thrown in that don't add anything.

He has a repository where he can add objects to,
modify objects in and delete objects from.

And he wants a method on the repository that persists
all the changes.

The purpose of the Save/Commit is to persists all the changes
to the objects.

Efficient backends will only save those.

An inefficient backend may actually rewrite the entire
repository.

But the naming of the method should reflect the purpose
not how an inefficient implementation could do it.

Arne

 

[Peter Duniho]

[...]

Given an XDocument, you can add, modify, and delete within the
XDocument. Calling the Save() method "commits" those changes to a file.

That is because the XDocument here is a single object that is being
modified - it is not being added or deleted.

Likewise, the repository in Miguel's example. So, if Save() works for
XDocument, why not for IAlbumRepository?

[...]
But the naming of the method should reflect the purpose
not how an inefficient implementation could do it.

There's nothing about the word "save" that implies an inefficient
implementation. The underlying implementation can do whatever it wants,
as long as all of the data winds up saved.

Pete

 

[Andy B.]

In fact when using Entity Framework I have:

public partial class Context : ISession {
public void Commit() {
SaveChanges();
} // Commit
public void Rollback() {
Dispose();
} // Rollback
}

But probably I should simple use Save instead of Commit and Dispose
instead of Rollback ...

That depends? I have seen in the entity framework things like this:

AlbumRepository.RejectChanges - Ignores anything done to the object before
"saving" it. I.e. the database's original version will be persisted instead
of the objects current state. More the less a rollback type of thing.
AlbumRepository.AcceptChanges - It will use the object's current state when
"saving" instead of the database's version of the data.
AlbumRepository.SaveChanges - sends all of the changes to the database (or
wherever) you actually want it to go.

In a simple example, if you have a save button on a windows form:

1. The person clicks the save button.
2. Changes are detected and a confirmation dialog appears with "Continuing
the save process will permanently overwrite all current data. Are you sure
you want to continue?".
3. In code, you detect wether the yes/no button was used and do the right
action:
- If yes, call .AcceptChanges and then SaveChanges.
- If no, call .RejectChanges [throw away the changes] and then
SaveChanges().

I don't know if I would use something like ObjectContext.Dispose for a
rollback operation. It might do what you want it to, but it makes coding
very interesting since you will need to recreate the objectContext again
whenever you want to actually use it.
//This is seudo code
if(DialogResult == "yes") {
AlbumRepository.AcceptChanges();
AlbumRepository.SaveChanges();
}
else {
//here is a problem...
AlbumRepository.Dispose();
}

Now, you want to use AlbumRepository to do something else. You will have to
recreate it again.

Either way it goes, it looks like managing, detecting and saving changes in
the context are done by different methods. A rule I would try to stick by
(even I have problems with it sometimes), is: If the method starts to do
more than 1 specific detailed task, split it up into multiple methods.

Xdocument.Save() only writes the object to disk. It doesn't validate, detect
changes, accept/reject changes. It just writes the file PERIOD.

 

[Arne Vajhøj]

[...]

Given an XDocument, you can add, modify, and delete within the
XDocument. Calling the Save() method "commits" those changes to a file.

That is because the XDocument here is a single object that is being
modified - it is not being added or deleted.

Likewise, the repository in Miguel's example. So, if Save() works for
XDocument, why not for IAlbumRepository?

Because when you save an XML document you are interested in saving
the entire document.

For the repository you are only interested in saving those things
that have changed.

[...]
But the naming of the method should reflect the purpose
not how an inefficient implementation could do it.

There's nothing about the word "save" that implies an inefficient
implementation. The underlying implementation can do whatever it wants,
as long as all of the data winds up saved.

Save implies that the entire object is saved. That is an inefficient
implementation compared to only saving those parts changed.

Arne

 

[Peter Duniho]

[...]
Given an XDocument, you can add, modify, and delete within the
XDocument. Calling the Save() method "commits" those changes to a file.

That is because the XDocument here is a single object that is being
modified - it is not being added or deleted.

Likewise, the repository in Miguel's example. So, if Save() works for
XDocument, why not for IAlbumRepository?

Because when you save an XML document you are interested in saving
the entire document.

For the repository you are only interested in saving those things
that have changed.

I find the distinction arbitrary. In both cases, the state of the
entire entity can be considered to have been changed.

At the API level, there is nothing about a Save() method that would
require the entire file to be rewritten from scratch. Even the
documentation for XDocument.Save() does not promise that the file will
be rewritten from scratch, even if that is the most likely implementation.

[...]
But the naming of the method should reflect the purpose
not how an inefficient implementation could do it.

There's nothing about the word "save" that implies an inefficient
implementation. The underlying implementation can do whatever it wants,
as long as all of the data winds up saved.

Save implies that the entire object is saved.

It in no way does that.

Pete