Over a million developers have joined DZone.

Consistency Matters!

A list of style guides for various languages to improve consistency between method names, interfaces, and more when writing software.

· Java Zone

Microservices! They are everywhere, or at least, the term is. When should you use a microservice architecture? What factors should be considered when making that decision? Do the benefits outweigh the costs? Why is everyone so excited about them, anyway?  Brought to you in partnership with IBM.

Consistency in software development involves the normality between method names, interfaces, and more. Consistency issues during software development should be addressed through the arrangement of individual pieces. These arrangements can differ from system to system, as well as a software team’s preferences. In my opinion, a team’s preferences matters more than anything else; however, it should still conform to most of the style guidelines. I’ll go through some examples through this post and make consistency cases concrete with examples.

Greenfield Project

This is the almost easiest case to handle. A team should define their style guides for themselves based on well known style guidelines. These guidelines may differ from one language to another. Recommended style guidelines for popular languages are as follows:

There are many other language style guides that could have been listed here but I preferred to keep my list short. The point is basing team’s style guide around widely accepted style guidelines. Once a team has a base, than they can update their guidelines according to their preferences. One might use IDE support to conform to coding conventions.

Legacy Project

It’s fun to start a new project but it’s not possible most of the times. So, a team might need to take over a legacy project where project doesn’t conform to well known guides. First of all, it’s almost impossible to refactor every piece of code to make it conform to well known style guide. Even if it was, it would probably take great amount of time. So, my suggestion here is to conform to existing style guide if there exists any. For example, if legacy python project has used camel case consistently instead of snake case throughout the project, I would not try to change that. Plus, I would follow that to make it consistent within the code base.

I’ll go through some easy cases:

  1. Use of abbreviations
    Sometimes, one would use abbreviations lowercase instead of uppercase. You might feel like changing it but I think one can again conform to it if it’s consistently used through code base.
    public void getSql()
  2. SQL mapping
    One might prefer column index over column label. Again you might want to change it but it’s easier to conform what’s already there than introducing something label index or column index.
    rs.getString(1)
  3. Whitespaces
    A python project might have one line between functions although convention is to use two. If all the functions conform to one line style, than it’s ok to conform to this convention.
    def getUser(id): pass
    
    def getMap(id): pass
  4. Comments
    I believe code should speak for itself so I would keep comments as little as possible. It’s unnecessary to have comments for simple methods. However, if code base has already comments for all simple methods, one should follow that style.
<?php 
/** 
* Convert an object to an array 
*
* @param object $object The object to convert 
* @return array 
* 
*/ 
function getArrayFromObject($object){ //implementation } 
?>

We could give many other examples but I want to keep it short. The point is to conform to styles that are already present within the code base.

In consequence, code consistency matters for readability and understandability. It’s an aspect a team should agree on. Changing coding style is hard so it’s better to conform to what’s already there.

Discover how the Watson team is further developing SDKs in Java, Node.js, Python, iOS, and Android to access these services and make programming easy. Brought to you in partnership with IBM.

Topics:
design ,programming ,clean code

Published at DZone with permission of Yusuf Aytaş, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}