Naming Conventions - Word Ordering

[Hooman]

So the subject of Stream classes came up. It got me thinking, what's the desired naming convention? Rules of English might dictate a certain word order, though programming is not English. Nor do all programmers speak English. And even if they did, choosing programming conventions because they match or are close to English seems like a weak argument at best. This got me thinking, more logical ordering of words that match some sort of hierarchy might be preferred. For instance:

Code: [Select]

Stream
SeekableStream  (English order)

Code: [Select]

Stream
StreamSeekable  (logical/hierarchical order)

This can continue on to other derived types:

Code: [Select]

FileReaderStream  (English)
StreamFileReader
StreamReaderFile

One of my considerations, is what is most useful for Intellisense popups. Having a common Stream prefix means all available options are grouped together, making it easy to see at a glance what is available.

Another thought is to include the "Stream" part in the interfaces, but omit it from the derived classes. Perhaps the Reader/Writer part is enough to imply something is a stream.

Code: [Select]

Stream
StreamSeekable

FileReader (or ReaderFile)
FileWriter (or WriterFile)

Perhaps the biggest concern, what makes the most sense to other people?

[lordpalandus]

I find with my own game that mentioning the type of code at the start helps me to better sort things and to more easily at a glance know what part of the code base I'm dealing with.

So I'd recommend (logical/hierarchical order):

StreamDamage
StreamSeekable
StreamTranslation

[leeor_net]

Another thought is to include the "Stream" part in the interfaces, but omit it from the derived classes. Perhaps the Reader/Writer part is enough to imply something is a stream.

Code: [Select]

Stream
StreamSeekable

FileReader (or ReaderFile)
FileWriter (or WriterFile)

Perhaps the biggest concern, what makes the most sense to other people?

This is kind of a tough one for a few reasons.

I would go with the last mentioned naming convention as quoted above. That's how I would do it. The interface describes it well enough and there's something to be said about overdoing the verbosity in names.

On the other hand, if you know you're looking for a StreamXXX type object, autocomplete's in modern IDE's are greatly assisted by using the more verbose name. You know you're looking for a Stream type object so you start typing in Stream and your IDE autocomplete shows you what's available.

On the other hand, if you are aware of the Stream interface and you know you need file based stream reader, the less verbose is more helpful because you start typing in File and you get the two options of Reader or Writer. Then there's the Memory stream, Zip stream (probably same as file, tbh), etc.

So yeah... it's a difficult subject but personally I vote for the less verbose option stated above. You shouldn't be using an interface without having done at least a little bit of reading and using appropriate documentation comments will help modern IDE's provide that documentation in their autocomplete anyway.

[Vagabond]

I understand what you are saying about everyone not speaking English. It is easy understanding coding coming from English as a first language. Unfortunately, you cannot (or at least should not code) in multiple languages. So if you are going to create source code readable by the widest audience, English makes sense. But whatever language is chosen, I think the variable and function names should  be a healthy mix of being terse, precise, and reading similar to how you would naturally read from that language. Even if someone is learning English as a second language to program with, forming the variables in a way that makes sense in English will probably still be helpful to them.

When reading the class name SeekableStream, it makes more sense to me than StreamSeekable. While I like the argument that writing StreamSeekable makes it easier to find with Intellisense (or the non-Microsoft equivalent), the counter to this argument is that when I'm reading a block of code, I will recognize what SeekableStream is/does quicker than StreamSeekable. I'd look at other libraries outside of C++ as well and try to mimic their choice of wording. I think SeekableStream is used more so than StreamSeekable.

You shouldn't be using an interface without having done at least a little bit of reading and using appropriate documentation

I'm guilty of just trying to find the proper function in Intellisense and applying it and going back later to research if it isn't working as advertised, or I'm feeling like I need to know more about it because others will be using my code. Maybe this is lazy, but it is reality and happens all the time.

Another thought is to include the "Stream" part in the interfaces, but omit it from the derived classes. Perhaps the Reader/Writer part is enough to imply something is a stream.

I like this idea for FileReader and FileWriter. I think as a user, it doesn't actually matter that you are using a Stream to read the file into memory for me. I just care that you are providing me the contents of the File. If it starts to matter more, I'll be able to see the interface or base class attached to FileReader that is called Stream with a bit of investigation.

Anyways, whichever you the 2 you choose I think will work fine and be readable.

-Brett

[leeor_net]

You shouldn't be using an interface without having done at least a little bit of reading and using appropriate documentation

I'm guilty of just trying to find the proper function in Intellisense and applying it and going back later to research if it isn't working as advertised, or I'm feeling like I need to know more about it because others will be using my code. Maybe this is lazy, but it is reality and happens all the time.

I'm also guilty of this... mostly in my past. Over the years I've learned that it takes far less time to get through what I'm working on by doing a little research into the API/Interface/Whatever before I try to use it. If there's a specific task I'm trying to accomplish, a quick google search will tell me exactly what I need to do and why. If I have further questions, again google is my friend. This assumes, of course, that said interface/api/whatever is well used. Otherwise a quick stroll through the header documentation is usually enough.

[Hooman]

I used to do that all the time. Usually it worked out. Saved a lot of time, not having to look things up, and got things up and working quickly. Probably a sign of a well designed API if you can guess how to use it from the class/method and parameter names.

As for consulting docs first, I think I've come to worry too much about doing things right, which really slows down development sometimes. It's likely far better to accept a few mistakes and imperfections, and iterate on them to something better, rather than constantly stopping to figure things out to try and make things perfect on the first try. Of course knowing this is not the same as doing this. This very thread is about trying to get things right before releasing anything.


Seems there's are a few different preferences too. Looks like asking the question didn't make deciding on an answer any easier.