In part 1 of the series "Give Clean Code the Importance it Deserves" we went over some questions like: What is clean code? Why is it important? How important is a programmer’s native language in all this? and How can stakeholders and programmers approach the matter? .

Now, if you feel like it is time to do something about the readability of your code, this part of the post is for you.I will provide some links to material I found useful and comment on some of the stuff found in them. I will also be showing you some real examples of unhappy code I had the luck of running into, and I hope that after all this you can enjoy a bit more your programming experience.

.NET Framework guidelines

https://msdn.microsoft.com/en-us/library/ms229042(v=vs.110).aspx

These guidelines are quite useful in creating a standard that everybody in the team can follow. Standardization is key in making readable code. You see, standards help form a common understanding among the team. Code that does not comply with the standard creates confusion. You will need extra time to figure out why there was a change in the “rules” for a particular piece of code.

There is one naming guideline that mentions the English-readability of a property, which is something I have mentioned in part 1. It is fairly common to see it happen when working with distributed teams in other parts of the world. If the names you use in your code don’t read well in the language of the client (English in our case) you are bound to have problems.

A variable or method with a poor name is not so much different from a minimized variable or function(in JavaScript, see part 1 of the post). The whole purpose of naming memory addresses is to give more meaning to an algorithm and thus simplify its understanding, otherwise we would still be coding in Assembly (if you still do, I apologize and feel sorry at the same time ). Let’s see some examples:

See example

This one came to me a couple of months ago, from a developer in another continent. When I first saw this it took me by surprise, I had no idea what that property could be used for, so I had to investigate how it was being used by the rest of the code to understand it. “IsUserExists” does not read well at all. It is confusing. “UserExists” alone would have been better, but still confusing… user.UserExists? if I have an instance of User, it kind of “exists”. After some investigation I found that this property was true if the user was registered in another system called AEM.

I would have called this property “IsAEMUser” or “IsRegisteredInAEM” for example and save everybody else a lot of time. This is an example of a property name that required unnecessary understanding of its context to understand its purpose… just as if it was named “a”.

Here is another example with a method:

BulkResetPasswordValidateUser sounds weird… it seems to be a 2 in 1 method. It resets passwords in bulk and it also validates the user right?  Not so fast…
The method has a comment on top that reads: ” To validate user for bulk reset password”

Ok, so this is different… it seems that the method validates if a user can perform a bulk password reset, but again, the comment is not clear enough, plus the method returns a list of a poorly named type, instead of a boolean. So, is it a validation method? does it perform an operation in bulk? what’s with the passwordResetModel parameter? is this method doing more things than it should? is the comment current or old?

At this point I have no idea what this method does and it forces me to go into the logic of the method to understand it. This is completely unnecessary. A little bit more time spent around this name, maybe another pair of eyes looking at it would have saved me a lot of time. This is an example of poor English mixed with poor class design messing up code. If you have to program in English and feel weak on the language, don’t hesitate in getting trained. It will improve your code significantly.

Read full post...