Code convention

[Gustavo Matias]

Hi Clean Coders,

I work on some customer projects where code conventions are taken very seriously, and I would like to share some thoughts with you and hopefully get any feedbacks.

The convention is:

1. Interfaces should start with the prefix "I"

2. Abstract classes should have the "Abstract" prefix

3. Function arguments should have the prefix "p"

4. Local variables should have the prefix "o"

5. Global variables should have the prefix "m"

It was a bit weird for me at first, but eventually I got used to it and found some of them very useful, let me try to tell you why:

1. I know that episode 2 mention about the "I" prefix and that it's unnecessary since the IDE tells us what is class and what is an interface. However, I found it very useful and more convenient in spring projects when using the "interface injection". For instance, I usually have an interface called "IVASTParser" and its implementation called "VASTParser". In order to avoid the "I" prefix, I've seen some people either calling the interface "VASTParser" and implementation as "VASTParserImpl", or having both called "VASTParser" but the implementation in a com.my.project.impl package. I personally think they sound a bit worse. does anybody have any better recommendation? or why should I use one or the other?

2. I partially agree that the "Abstract" prefix is unnecessary, but sometimes I think it's convenient to search for an abstract class by using Eclipse's shortcut (CTRL + SHIFT + T) and start typing "Abstract" so it filters nicely.

For 3, 4 and 5. I started to like it because it helps me when reading the code and knowing the exact scope of the variables/objects. Sometimes I have to deal with huge classes/functions and those prefixes kind of help.

Which also brings me to another last question, should global variables try to be avoided? if so, what's the alternative?

Any thoughts?

[Paolo Laurenti]

Hi Gustavo,

[...]

1. I know that episode 2 mention about the "I" prefix and that it's unnecessary since the IDE tells us what is class and what is an interface. However, I found it very useful and more convenient in spring projects when using the "interface injection". For instance, I usually have an interface called "IVASTParser" and its implementation called "VASTParser". In order to avoid the "I" prefix, I've seen some people either calling the interface "VASTParser" and implementation as "VASTParserImpl", or having both called "VASTParser" but the implementation in a com.my.project.impl package. I personally think they sound a bit worse. does anybody have any better recommendation? or why should I use one or the other?

I think that the "I" prefix on interfaces name are useless. If you have IVASTParser interface and an object implementation that have the same name without I-prefix, means that you are missing an abstraction inside your objects domain. 

You have to use an interface in order to abstract a role played by some object, hiding every implementation details that don't concern the high level policy that are represented by your interface.

So: I think you could have a "VASTParser" interface inside an High Level Policy Package and a class called "<SOME_IMPLEMETATION_DETAIL>VastParser inside a Low level Policy Package. Tell  me if my explanation isn't clear, I will try in another way :-).

 

2. I partially agree that the "Abstract" prefix is unnecessary, but sometimes I think it's convenient to search for an abstract class by using Eclipse's shortcut (CTRL + SHIFT + T) and start typing "Abstract" so it filters nicely.

My reply to point 1 can be considered also with point 2. I think that if it isn't clear that the class name represent an high level abstraction reading only the class name, it can be considered a design smell. Is it so important to know immediately if an object we are viewing inside the code is an Abstract class or an Interfaces? In my opinion, no it is not important.

 

For 3, 4 and 5. I started to like it because it helps me when reading the code and knowing the exact scope of the variables/objects. Sometimes I have to deal with huge classes/functions and those prefixes kind of help.

I think that the prefixs that you mentioned are useless and can only make the code ugly. If you need to know if a variable is a function parameter or local instance, it means you have a problem. It means (and you confirmed) that you're dealing with large classes/ functions and it is bad. In this case, I suggest you to refactor your classes/functions in order to make smaller classes/functions and to split responsibilities. (Watch the firsts videos about Clean Code, there are beautiful examples made by Uncle Bob)

 

Which also brings me to another last question, should global variables try to be avoided? if so, what's the alternative?

Any thoughts?

Yes, they should be avoided. Try to inject dependencies needed by objects, inside classes constructors. This make code more readable and testable because it highlights what is needed by an object to make its job.

I hope this could help :-) 

--
The only way to go fast is to go well.
---
You received this message because you are subscribed to the Google Groups "Clean Code Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to clean-code-discu...@googlegroups.com.
To post to this group, send email to clean-code...@googlegroups.com.
Visit this group at http://groups.google.com/group/clean-code-discussion.

[Bartosz Borowik]

Hi Gustavo,

I don't quite agree with your argumentation. I used to think the same way (or at least similar) earlier, but then I realized that such a constrained naming conventions introduce additional unnecessary coupling.

Classes should be named only after what an object of the class does/is and how it does that. You should put yourself in the position of a user of your class and answer the question if there's any benefit for you knowing explicitly that you're using an interface? Is it not enough for you to simply know that an object you're holding a reference to is able to do some action? And that is described by the content of the class not by the additional "I" in front of it's name. So:

1. The "I" prefix is superfluous in that it does not give additional information about what an object is/does. In your case I would name the interface VastParser and the default implementation simply DefaultVastParser

2. The same arguments as above would make me leave the "Abstract" prefix away.

Variables should be named only after what information they hold and not where they're defined or in what scope they reside. Just imagine what additional amount of work will you have adjusting your code (tests and production), when you move a variable from one scope to the another. Such conventions tend to be not respected very strictly and you end up with variables beginning with "o" being function arguments or residing in the global scope. So:

3., 4., and 5. don't do that

- Bartek

[Caio Fernando Bertoldi Paes de Andrade]

Micah Martin does a very good job explaining why the IConvention isn't really the best idea (and gives insights about the other issues raised here):

http://blog.8thlight.com/micah-martin/2006/09/07/ilist-icomparable-icarumba.html

Hope this helps,

Caio

—
Sent from Mailbox for iPhone

[Uncle Bob]

Make sure you read the last line...

I reject all of these conventions; and I reject them rather vehemently.  

1&2. The whole point of an interface is that the user does not know that it is an interface.  Why, then, would you scream that information to the user.  The same is true  of an abstract class.  The users of an abstract class aren't supposed to know that it is abstract.  That information is private to the author.  Don't broadcast it.

3,4. Don't use argument, local, and member prefixes.  Instead, use well named arguments and members.  Limit your functions to three or fewer arguments.  Keep your functions so small that you can't get confused between arguments, members, and local variables. 

5. I don't know your language, but it is better to put global variables into a special well-named namespace.  A class will do.  Something like this:

public class Global {

 public static int sessionCount;

}

Finally.  Don't publish your coding conventions.  Instead, let your code be the example.  The only reason to publish separate coding conventions is because your code doesn't follow them.  

*****

Having said all of that, let me also say this.  If you are already working somewhere that is using bizarre conventions, then follow them.  Following conventions is more important that common sense.  Wait for a new project before you change the conventions.

[Gustavo Matias]

Thank you all! this is very clear and I totally agree with you guys.

Unfortunately I can't just stop using those conventions right away because my teammates would kill me and might even lead to some sort of confusion for those that have been dealing with it for years. but as Uncle Bob said, I'll try to introduce it once I start working on a brand new project!

Thanks!