Writing to myself

Escribiendo para mi mismo

Coding Etiquette

I know, right? This used to frustrate me a lot, but hey! its not the end of the world.

Prior this entry, there has been some attempts on the team I work with to come up with guidelines or rules to use in our development process. Rules tend to force and condition a specific behavior, and even when the team has agreed to use them, its difficult due such guidelines - the common ones - ask for a change on how developers write their code, at the end, its a give and take that not every team member might be happy with.

On the other hand, an etiquette describes a code of behavior in a specific social context. If we land this in our professional environment, it is expected from a senior developer to have similar habits and standards to maintain an order that will be beneficial in the development process. As I previously mentioned, an etiquette does not force a behavior as oppose to a rule (so developers can still choose not to follow them), but it sets expectations level for everyone in the team.

Straight to the business, these are the etiquettes I think every development team should use - there might be more, and i will add them once they come to my mind:

Reusability

Have you heard about the principle “Don’t Repeat Yourself” (DRY)? It states that specific components should only occur once in your system. Having this in mind, if you are in the need to add a new component AKA method, class, etc, consider the following steps/questions:

  • Is there something similar already to what I want to add?
  • If Yes, then - does it do what I need?
  • If No, then - can I update it?

And we can continue with more questions like this. The goal is to avoid having repeated components that might be doing the same. Remember duplication in code is a bad practice.

Commenting

Commenting your code can be a good tool to avoid things like “When I wrote this, only God and I understood what I was doing. Now, God only knows”.

If the method you are implementing has or will have a big bunch of code, consider breaking the logic into steps, if those steps require some kind of assumption, do not hesitate to add it as a comment (it might be an assumption for you but not for others).

The goal is not to comment every single line of code but to comment a series of steps that achieve a particular objective.

This will help other developers to understand why things were done like that, and in the event of adding new code, information like that will be helpful to define where to inject it.

Lastly on this point,

  • Comment anything that is unusual on a normal flow, for example, if you want to avoid calling the super implementation of a selector, be sure to add the comment.
  • If a method is purposely left empty, add the comment.
  • If you find something subject to be improved (or moved, deleted, etc), or when you added or saw a hacky fix that needs immediate refactor, add a //TODO:

Naming Conventions

Usage of proper naming conventions is considered a good practice. We prefer “Camel Case” naming convention (capitalizes the first character of each word except the first word).

For variables:

Name your variables keeping in mind the purpose they will be used. If your need to store the width value of a specific view, avoid using names such as “x” and consider “searchBarWidth” instead, if this becomes problematic the use of “width” does the job too.

Most developer prefer the usage of a prefix that describes the class name. For example:

1
2
MKMapView *mapStores;
UILabel *lblTitle;

For methods:

Name your methods keeping in mind the main objective to be achieved within them.

As an example, if you need to create an action where the first object from the list needs to be selected, do something like this:

1
2
[sender selectFirstItem];
[sender selectFirstCategory];

instead of

1
[sender selectFirst];

Another example can be, if you need to create a method to dismiss the current view controller, you can do:

1
[sender dismissController] 

instead of

1
[sender cancel];

For methods with multiple parameters, consider the following example. If you need an action where we need to add a payment to a receipt, you can do:

1
[sender addPayment:toReceipt:];

Avoid adding the word “and” in the parameter names.

1
[sender findItemWithType:andPk:];

For completion blocks, words likes “onComplete”, “onSuccess”, “onFailure”, “doAfter” are acceptable.

For UnitTesting methods, always start with the word “test”.

Giving Feedback on Pull Request

This can be considered a difficult task since there is the need to draw a line on things that needs to be changes for approval and things that are acceptable but don’t block the approval.

Consider the usage of the following phrases when writing your feedback:

  • “Must Fix”: Meaning no approval until its changed.
  • “Suggestion”: Approval is not compromised but its under developer discretion to change the code.

What scenarios will make us use the previous phrases? For that, ask yourself the next questions:

  • Does it achieve the goal?
    • If Yes, then most likely you will be just adding suggestions.
    • If No, then a must fix should be requested.
  • Does this approach increase the project technical debt?
    • Don’t hesitate to express that something needs to be changed due reusability is not achieved as it should be.
  • Is there any database change?
    • Be careful with this one, and most likely you will request a must fix.
  • Does this code brake existing unit tests?
    • If so, its an easy answer, you should request a myst fix.

Writing Unit Test

Think of unit test as a safety net you add to the logic you just implemented in a given task. If there is new code injected in the same area where the unit test are working, you can know if the behavior has change prior any manual testing.

It is a good practice to have the following things in mind while writing unit tests:

  • They should be defined before any code change is made, if you do the opposite, most likely you will have to go back a touch the code to make the test pass.
  • Gherkin language (Given, When, Then, etc) is useful to describe what you are testing.
  • Test should be testing small independent bunch of code.
  • More than one assertion is acceptable if they are related. If not, only one per test.

Technical Debts & Refactoring

In every codebase you might find code that meets the following criteria:

  • Is out of date and requires immediate change, but if you proceed, it might and most likely affect other areas.
  • Due a time constraint you decided to implement a patch knowing you need to come back later.
  • There is a better or newer way of doing something.

When doing such discovery, raise the voice and have a technical debt created for you for future implementation (you should reach the lead developer for this), don’t do the change if you are unsure of the impact it might cause.

Letting other people know about the discovery can have additional benefits such as:

  • Doing the change right away due there was no severe impact on it.
  • Understanding why it was done that way (specially when no comments were added).

Small General Etiquettes

The following ones are project specific or language specific.

  • Line Length: 120 (not strict limit).
  • Use default spacing (4 spaces).
  • The usage of constructor or initializer methods is well received.
  • Any new string added to the project should use NSLocalizedString macro.
  • When submitting Pull Request, remove commented code and discard any changes that is unrelated to your fix/implementation (specially with storyboards).
  • The usage of pragmas to organize code is well received.

Conclusion

Working in a team might be not be an easy task, specially for people like me obsessed with order. As you can see, these etiquettes do not ask developers to change how they use spaces in methods declarations, semicolons in conditionals, block the usage of ternary operator, etc. But they do ask for a common behavior when working in a team, to keep things as objective as possible. And again, in a professional environment, habits like this should already exists on the individual, specially in those ones with a lot of experience.

Javier Azuara