C# terminology questions

[Ron Bullman]

Hi,

I haven't been able to find proper (commonly agreed) names for the following
kinds of methods.

Class (static) methods:
c1) returns value, doesn't modify the content of its argument(s) and
doesn't change the state of class (class accessor?)
c2) returns value, doesn't modify the content of its argument(s) and
changes the state of class (class mutator?)
c3) returns value, modifies the content of its argument(s) and
doesn't change the state of class (class ?)
c4) returns value, modifies the content of its argument(s) and
changes the state of class (class mutator?)
c5) doesn't return value, doesn't modify the content of its argument(s) and
doesn't change the state of class (useless?)
c6) doesn't return value, doesn't modify the content of its argument(s) and
changes the state of class (class mutator?)
c7) doesn't return value, modifies the content of its argument(s) and
doesn't change the state of class (class ?)
c8) doesn't return value, modifies the content of its argument(s) and
changes the state of class (class mutator?)
Instance methods:
i1) returns value, doesn't modify the content of its argument(s) and
doesn't change the state of instance (instance accessor?)
i2) returns value, doesn't modify the content of its argument(s) and
changes the state of instance (instance mutator?)
i3) returns value, modifies the content of its argument(s) and
doesn't change the state of instance (instance ?)
i4) returns value, modifies the content of its argument(s) and
changes the state of instance (instance mutator?)
i5) doesn't return value, doesn't modify the content of its argument(s) and
doesn't change the state of instance (useless?)
i6) doesn't return value, doesn't modify the content of its argument(s) and
changes the state of instance (instance mutator?)
i7) doesn't return value, modifies the content of its argument(s) and
doesn't change the state of instance (instance ?)
i8) doesn't return value, modifies the content of its argument(s) and
changes the state of instance (instance mutator?)

Any ideas where to find such terminology defined in C# (and/ or .NET)
context? It would be good to know also what kind of unofficial names are
used by practitioners?

Also in what kind of situations it is acceptable to use such methods which
modifies the content of its argument(s) (c3, c4, c7, c8, i3, i4, i7, i8)?


Ron

 

[Marina]

I don't think c5 is useless. For example, a method whose sole purpose it is
to send out an email. It doesn't return anything, it doesn't modify its
argument because it simply uses them to send an email, and it doesn't change
the state of the class it is in, because that is irrelevant.

I do not know the official names for these kinds of methods, but I have
never encountered a situation where it has been necessary to name them.
After all, these are just concepts, is there really a need to label each
type of method?

Methods that modify its arguments could be a method that updates all the
rows in a dataset to have a particular value in a column.

Or a class that takes an asp.net control, and sets a particular property on
that control to a value (perhaps there is some logic that it uses to
determine this value).

Or, to give a .NET framework example, the Sort method of the Array class. It
accepts an array to sort as the argument, and then sorts it. After the
method call, the argument has been sorted.

 

[Ron Bullman]

Hi Marina,

Thanks for your reply. My comments inlined.

Ron

I don't think c5 is useless. For example, a method whose sole purpose it is
to send out an email. It doesn't return anything, it doesn't modify its
argument because it simply uses them to send an email, and it doesn't change
the state of the class it is in, because that is irrelevant.

But shouldnt such method return somekind of indication wheter the sending
was succesfull or not?

I do not know the official names for these kinds of methods, but I have
never encountered a situation where it has been necessary to name them.
After all, these are just concepts, is there really a need to label each
type of method?

But pretty important concepts indeed and I have seen a lot of code where the
programmers intention havn't been clear enough. If we (really) have 16
different kind of behaviours associated with the methods then it definitely
would be useful to distinguish them by proper naming as well. Although I'm
not sure at all if all of those 16 is needed.

Methods that modify its arguments could be a method that updates all the
rows in a dataset to have a particular value in a column.

Why would you prefer this instead of instance method mutating its state?

Or a class that takes an asp.net control, and sets a particular property on
that control to a value (perhaps there is some logic that it uses to
determine this value).

Or, to give a .NET framework example, the Sort method of the Array class. It
accepts an array to sort as the argument, and then sorts it. After the
method call, the argument has been sorted.

What method you are refering here AFAIK there doesen't exist such method in
System.Collections.Arraylist

 

[Edwin Kusters]

Gotta be fun to watch this app after it reaches version 3.2 and see how many
standard names actually still match with what they do.

Over standardisation of naming conventions lead imho to more problems then
they solve.
You are already up to 16 names that involve a combination of just 3
criteria. If a method is defined
as void it does not return a value. If an argument is ref it expects a value
and will change it. if an argument is out is may get a value set. Use common
sense names for your methods that people can understand. And last but not
least use that lovely /// syntax to write readible comments about what the
thing _actually_ does.

Strong types (.net) and a well designed grammar (C#) are a heaven compared
to for instance vb6. It's not without a reason that naming conventions for
C# (have a look at fxcop) no longer includes hungarian notation.

What naming conventions should do is make sure that coders aren't tricked
into expecting something else than what actually happens.
UpdateEmailAddress() ending up deleting it
QueryEmailAddress() making modifictions to it.
Stop() not stopping (erm perhaps I should change my expectations about this
one, seen too many over the years that don't)
etcetc

As for an example of changed arguments: any function that returns multiple
values where it really doesn't make much sense to put them in some
collection. From the base classes: (threadpool)

public static void GetAvailableThreads(
out int workerThreads,
out int completionPortThreads
);

This function declaration tells me all I need to know (void, 2* out args).
The two things it does not tell me is if those out params may be null after
the call and which exceptions might be raised. Which I actually would like
to know. Your current naming convention proposal also won't resolve that
without further extending it.

My 2 cents

Edwin Kusters

 

[Jon Skeet]

But shouldnt such method return somekind of indication wheter the sending
was succesfull or not?

No. It should throw an exception if it's not successful. How about a
method which just squirts the current state of the class to the
console? Very handy, but it's not going to know whether it truly
succeeded or not, apart from by whether or not Console.WriteLine (etc)
throws an exception.

But pretty important concepts indeed and I have seen a lot of code where the
programmers intention havn't been clear enough. If we (really) have 16
different kind of behaviours associated with the methods then it definitely
would be useful to distinguish them by proper naming as well. Although I'm
not sure at all if all of those 16 is needed.

But there are even more - there are those which modify the object
referred to by a parameter, and those with ref/out parameters which
modify the parameters themselves, for instance. I really don't think
there's much point in having vast numbers of names for such things. Far
better is to just document what's going on in the XML: if a parameter
is to be changed (in either way) that should be documented clearly. The
return value is documented in the obvious way, and class/instance
changes should also be documented (in a non-implementation-specific
manner) in the summary.

Why would you prefer this instead of instance method mutating its state?

I would generally prefer an instance method. It's not always possible
though, for various reasons.

What method you are refering here AFAIK there doesen't exist such method in
System.Collections.Arraylist

No, but there *does* exist such a method in the System.Array class.

 

[Ron Bullman]

No. It should throw an exception if it's not successful. How about a
method which just squirts the current state of the class to the
console? Very handy, but it's not going to know whether it truly
succeeded or not, apart from by whether or not Console.WriteLine (etc)
throws an exception.

Agreed (assuming the mail transfer is very reliable).

But there are even more - there are those which modify the object
referred to by a parameter, and those with ref/out parameters which
modify the parameters themselves, for instance. I really don't think

Yes, indeed plenty of combinations and therefore the possibility to get
confused of the programmers intention rises as well.

there's much point in having vast numbers of names for such things. Far
better is to just document what's going on in the XML: if a parameter
is to be changed (in either way) that should be documented clearly. The
return value is documented in the obvious way, and class/instance
changes should also be documented (in a non-implementation-specific
manner) in the summary.

Yes, good dodumentation is necessity and perhaps this is not such big issue
while you are reading/ writing the specific code itself, but I encounter
difficulties when trying to discuss this topic on more general level and
therefore I was hoping to find some better terminology of different kinds of
methods. C# allows you to mix OO and preocedural concepts but it should
allways be clear what's the intention, perhaps some combinations just don't
rock.

I would generally prefer an instance method. It's not always possible
though, for various reasons.

Such as?

No, but there *does* exist such a method in the System.Array class.

My mistake (it seems that I'm still learning to read ).
However there seem to be some kind of "hidden" meaning why the Array class
has been composes this way. At least for me this meaning isn't very clear.
Why there exists such mix of instance and class methods in the Array class?

Ron

 

[Jon Skeet]

Agreed (assuming the mail transfer is very reliable).

Why the assumption? I believe an exception is the most appropriate way
to go here however reliable the mail transfer is.

Yes, indeed plenty of combinations and therefore the possibility to get
confused of the programmers intention rises as well.

Yes, if it's not documented clearly. Good documentation and detailed
description is much better than trying to remember dozens of single
names.

Yes, good dodumentation is necessity and perhaps this is not such big issue
while you are reading/ writing the specific code itself, but I encounter
difficulties when trying to discuss this topic on more general level and
therefore I was hoping to find some better terminology of different kinds of
methods. C# allows you to mix OO and preocedural concepts but it should
allways be clear what's the intention, perhaps some combinations just don't
rock.

When discussing the topic, use detailed descriptions - why should we
need to give them particular names?

Such as?

Such as you may not be the author of the class. For instance, if
Array.Sort didn't exist, I could still write MyArrayUtil.Sort, but I
couldn't add an instance method to the Array class.

My mistake (it seems that I'm still learning to read ).
However there seem to be some kind of "hidden" meaning why the Array class
has been composes this way. At least for me this meaning isn't very clear.
Why there exists such mix of instance and class methods in the Array class?

I don't know, to be honest. It does seem somewhat odd.

 

[Ron Bullman]

Gotta be fun to watch this app after it reaches version 3.2 and see how many
standard names actually still match with what they do.

Over standardisation of naming conventions lead imho to more problems then
they solve.
You are already up to 16 names that involve a combination of just 3
criteria. If a method is defined
as void it does not return a value. If an argument is ref it expects a value
and will change it. if an argument is out is may get a value set. Use common
sense names for your methods that people can understand. And last but not
least use that lovely /// syntax to write readible comments about what the
thing _actually_ does.

I wasn't so much suggesting to standardize the method naming convention it
selft, but I feel that there should exist such for any development project.
It's much harder to discuss unless you have meaningful names. And that's
what I have faced when trying to discuss of various kinds of methods in a
more general level than the specific code level.

Strong types (.net) and a well designed grammar (C#) are a heaven compared
to for instance vb6. It's not without a reason that naming conventions for
C# (have a look at fxcop) no longer includes hungarian notation.

IMHO C# is indeed well designed and usable language. But I can see also
problems emerging when you have to use assemblies from several vendors.
There's lot of C# source in the Internet and at least for me it's sometimes
pretty hard to try to find out the exact behavior.

What naming conventions should do is make sure that coders aren't tricked
into expecting something else than what actually happens.
UpdateEmailAddress() ending up deleting it
QueryEmailAddress() making modifictions to it.
Stop() not stopping (erm perhaps I should change my expectations about this
one, seen too many over the years that don't)
etcetc

As for an example of changed arguments: any function that returns multiple
values where it really doesn't make much sense to put them in some
collection. From the base classes: (threadpool)

public static void GetAvailableThreads(
out int workerThreads,
out int completionPortThreads
);

What would be the proper name to describe this kind of method, class
accessor?
Other issue is then that I'm pretty confused here why the arguments need to
be mutated? Can you explain why it's composes this way instead of providing
two separate methods:
public static int GetAvailableWorkerThreads();
public static int GetCompletionPortThreads();
or why not just provide two properties with getters only

public static int AvailableWorkerThreads;
public static int CompletionPortThreads;

This function declaration tells me all I need to know (void, 2* out args).
The two things it does not tell me is if those out params may be null after
the call and which exceptions might be raised. Which I actually would like
to know. Your current naming convention proposal also won't resolve that
without further extending it.

I'm not in any such position to propose any naming convention at large ;-).

Aren't methods sort of "micro interfaces" and shouldn't the meaning
associated with them be as straightforward as possible?

My 2 cents

Edwin Kusters

<skip>

Ron

 

[Ron Bullman]

Why the assumption? I believe an exception is the most appropriate way
to go here however reliable the mail transfer is.

I have allways thought that exceptions are for truly execptional situations.
So what is then truly execptional? I don't know but perhaps something
comparable to the reliability of hard disks.

Yes, if it's not documented clearly. Good documentation and detailed
description is much better than trying to remember dozens of single
names.

Useless to memorize such names if they don't carry any meaning. Frankly I
belive that these different kinds of methods and especially how they are
composed implies underlying concepts. Therefore it's better to have them
explicitly named as well.

When discussing the topic, use detailed descriptions - why should we
need to give them particular names?

When you are not in the situation (i.e. you are not reading/ writing the
code) it's easier and more understandable to discuss about it. I have
allways wondered why there has to exist implicit assumptions rather than
explicit knowledge.

Such as you may not be the author of the class. For instance, if
Array.Sort didn't exist, I could still write MyArrayUtil.Sort, but I
couldn't add an instance method to the Array class.

Yes understandable situation, but why the author originally did provide the
class method rather than instance method Inorder to speculate why
implemented as implemented it would be good to have proper terminology with
us.

class?

I don't know, to be honest. It does seem somewhat odd.

Yes, pretty unclear wht's the ideolygy behind here.

Ron

 

[Jon Skeet]

Gotta be fun to watch this app after it reaches version 3.2 and see how many
standard names actually still match with what they do.

Over standardisation of naming conventions lead imho to more problems then
they solve.
You are already up to 16 names that involve a combination of just 3
criteria. If a method is defined
as void it does not return a value. If an argument is ref it expects a value
and will change it. if an argument is out is may get a value set.

No, out arguments *always* have their values set, unless an exception
is thrown.

Note also that although non-ref/out parameters won't change in
themselves, the objects they refer to might - for instance, passing an
ArrayList reference into something which adds to it. That requires
documentation.

As for an example of changed arguments: any function that returns multiple
values where it really doesn't make much sense to put them in some
collection. From the base classes: (threadpool)

public static void GetAvailableThreads(
out int workerThreads,
out int completionPortThreads
);

This function declaration tells me all I need to know (void, 2* out args).
The two things it does not tell me is if those out params may be null after
the call and which exceptions might be raised. Which I actually would like
to know. Your current naming convention proposal also won't resolve that
without further extending it.

After completing normally (ie not throwing an exception), workerThreads
and completionPortThreads will be definitely assigned. They can't be
null, as int isn't a reference type.

 

[Jon Skeet]

I have allways thought that exceptions are for truly execptional situations.
So what is then truly execptional? I don't know but perhaps something
comparable to the reliability of hard disks.

I would normally expect a method to do what it says, and unless there's
a really good reason to pretty much expect it to fail (eg
String.IndexOf, where the searched-for string/character isn't present)
I'd rather throw an exception that return a value.

Useless to memorize such names if they don't carry any meaning.

I wasn't proposing memorising *anything*.

Frankly I belive that these different kinds of methods and especially how
they are composed implies underlying concepts. Therefore it's better to
have them explicitly named as well.

If the behaviour needs to be documented anyway, why invent more jargon
when the documentation can give the same information in a more
accessible way?

When you are not in the situation (i.e. you are not reading/ writing the
code) it's easier and more understandable to discuss about it. I have
allways wondered why there has to exist implicit assumptions rather than
explicit knowledge.

You don't need to be reading/writing the code in order to read the
documentation. I've never suggested implicit assumptions - I've
suggested explicit knowledge in plain language, rather than making up
extra jargon.

<snip>

 

[Jon Skeet]

There exists a lot situations where you need to discuss in general level
rather in specific/ detailed level.

And what's to stop you from using sequences of normal words in those
situations? I've never had a problem communicating that kind of
information. Why do you think we need more names when as far as I can
see the communication is happening perfectly well already?

Terminology is not same as jargon.

Indeed - but when you're suggesting giving names to things which can be
adequately expressed in a few well-understood existing words, I think
you're proposing extra jargon.

 

[Edwin Kusters]

What would be the proper name to describe this kind of method, class
accessor?

Good question Not so trivial to determine. My question is what added
value I get from knowing in this case?
The 'Get' part in the name does make me expect that nothing gets changed
with regards to threads.

Other issue is then that I'm pretty confused here why the arguments need to
be mutated? Can you explain why it's composes this way instead of providing
two separate methods:
public static int GetAvailableWorkerThreads();
public static int GetCompletionPortThreads();
or why not just provide two properties with getters only

public static int AvailableWorkerThreads;
public static int CompletionPortThreads;

For argument sake (of why such function should exist):
- If both values are directly related to eachother and are time dependant.
Ie if there is a direction relation between the AvailableWorkerThreads and
the CompletionPortThreads AND this relation is _only_ valid if both are
retrieved within a lock. Splitting this into 2 methods puts a requirement
onto the coders to apply the lock him (or her)self or he/she ends up with
comparing the wrong things. A nifty one to come up with a naming standard
for, not to mention it would be a poor design

- If both values are (almost) always used in conjunction and retrieving the
values is time consuming. Like when you drive to the supermarket and buy
some bread you will most likely also grab some other things while you are
there. It's just a waste of time to have to go back 2 mins after you got
home and realize you like to have something on your bread.

I'm not in any such position to propose any naming convention at large ;-).

Aren't methods sort of "micro interfaces" and shouldn't the meaning
associated with them be as straightforward as possible?

Yes, but what does your naming scheme add information wise that isn't
already there? It appears to me that your goal here it make method naming
deterministic. It means that you try to encode the methods behavior into the
methods name. In it's extreme that would imply that there really is no need
to write a method body since all expected behavior could be extracted from
the name and a decent compiler would just spit out the il for it
Eventhough I did indeed pick bad examples (thanks for pointing them out Jon)
the idea behind them is to point out that there are all sort of other issues
that cannot be determined by a methods name and requires some more elaborate
text (documentation). As things are today easy access to documentation is
key into using 3rd party assemblies effectively.

When it comes to naming conventions and even more method behavior I would
like to see a discussion about issues as:
- Should you call it GetAvailableWorkerThreads or
QueryAvailableWorkerThreads. Do we all agree that Get/Query are identical
words or do they imply different things. If they are the same let's all pick
one and stop using the other. If they are not let's all apply them in a
consistent fashion.
- Should a (supporting) method like sendmail throw exceptions or should it
return a statuscode (through some enum) leaving the choice if it is or isn't
an unexpected result to the caller.
In most cases it's not a methodname that bites me when using other people
assemblies but how the method is actually implemented. If your naming schema
would help in that area you have a fan. Until then you code conservatively.
(Like Jon said elsewhere in this thread: "pretty much expect it to fail ").
This means that in some cases you are writing more code than what is needed,
solve this and you save time and money.

Last but not least I'm curious how your naming schema could work on for
instance defining interfaces and how it deals with the naming of overloaded
or virtual methods

<skip>

Ron

Edwin